chanjs 2.7.2 → 2.7.4

package/index.js

@@ -1,20 +1,33 @@
 // 核心基础类导出
 export { default as Controller } from "./base/Controller.js";
-export { default as Service } from "./base/Service.js";
+export { default as Repository } from "./base/Repository.js";
 export { default as DB } from "./base/Database.js";
 export { Container } from "./base/Container.js";
 export { Aop, aop } from "./base/Aop.js";
 export { Event, event } from "./base/Event.js";
 
-// 工具模块导出
-export * as helper from "./helper/index.js";
+// 工具模块导出（按职责拆分，替代原 helper 大杂烩）
+export * as storage from "./storage/index.js";     // 缓存/Redis/存储适配
+export * as security from "./security/index.js";   // 关键词/XSS/签名/JWT/限流
+export * as realtime from "./realtime/index.js";   // SSE/WebSocket
+export * as loader from "./loader/index.js";       // 加载器
+export * as response from "./response/index.js";   // 响应格式化
+export * as utils from "./utils/index.js";         // 通用工具（时间/文件/HTML/IP/数据解析/树/过滤）
+export * as helper from "./helper/index.js";       // 聚合导出层（从各子模块 re-export，业务侧兼容）
 export * as middleware from "./middleware/index.js";
 export * as config from "./config/index.js";
 export * as common from "./common/index.js";
-export * as extend from "./extend/index.js";
 
-// 常用工具函数直接导出
-export { loadConfig, loaderSort, loadController ,cache} from "./helper/index.js";
+// 常用工具函数直接导出（顶层快捷访问）
+export { loadConfig, loaderSort, loadController } from "./loader/index.js";
+export { cache } from "./storage/index.js";
+
+// 定时任务调度器
+export { schedule, Schedule } from "./schedule/schedule.js";
+
+// 实时通信：SSE + WebSocket
+export { sse, SSEManager } from "./realtime/index.js";
+export { websocket, WebSocketManager } from "./realtime/index.js";
 
 // 路径配置
 export { Paths } from "./config/paths.js";

package/loader/index.js

@@ -0,0 +1,6 @@
+/**
+ * 加载器模块 - 配置加载/控制器加载/排序
+ * - loadConfig: 依赖 ESM 模块缓存（无 LRU，避免配置更新问题）
+ * - loadController: Symbol 标记幂等绑定
+ */
+export { loaderSort, loadConfig, clearConfigCache, loadController } from "./loader.js";

package/{helper → loader}/loader.js

@@ -27,26 +27,19 @@ export function loaderSort(modules = []) {
  * @async
  * @returns {Promise<Object>} 配置对象
  * @description
- * 从 config/index.js 加载配置，支持缓存机制
- * 如果存在缓存且未过期，则直接返回缓存值
+ * 从 config/index.js 加载配置
+ *
+ * 性能优化（P2 #21）：
+ * 删除 LRU 缓存层，直接依赖 ESM 模块缓存
+ * - ESM import 同一文件返回缓存的模块实例（Node.js 内置机制）
+ * - 旧版 LRU 缓存有 5 分钟 TTL，配置变更后不生效，需要手动 clearConfigCache
+ * - 现在配置变更直接重启进程即可，符合生产实践
  */
 export async function loadConfig() {
-  const cacheKey = 'chanjs:config';
-  
-  if (Chan.cache && Chan.cache.has(cacheKey)) {
-    return Chan.cache.get(cacheKey);
-  }
-  
   const configPath = path.join(Paths.configPath, "index.js");
   try {
     const module = await import(`file://${configPath}`);
-    const config = module.default || module;
-    
-    if (Chan.cache) {
-      Chan.cache.set(cacheKey, config, 5 * 60 * 1000);
-    }
-    
-    return config;
+    return module.default || module;
   } catch (error) {
     console.error("[Config] 加载配置失败", error.message);
     return {};
@@ -54,19 +47,23 @@ export async function loadConfig() {
 }
 
 /**
- * 清除配置缓存
- * @description
- * 删除存储在缓存中的配置数据
- * 下次调用 loadConfig 时会重新从文件加载
+ * 清除配置缓存（已废弃）
+ * @deprecated P2 #21 优化后，配置直接依赖 ESM 缓存，无需手动清理
+ * 保留函数仅为向后兼容，调用为空操作
  * @example
- * clearConfigCache();
+ * clearConfigCache(); // 空操作，无需调用
  */
 export function clearConfigCache() {
-  if (Chan.cache) {
-    Chan.cache.delete('chanjs:config');
-  }
+  // ESM 模块缓存由 Node.js 管理，无需手动清理
 }
 
+/**
+ * 已绑定方法标记（Symbol 幂等）
+ * 避免重复 loadController 时对同一方法多次 bind 形成嵌套
+ * @private
+ */
+const BOUND_SYMBOL = Symbol('chanjs:bound');
+
 /**
  * 加载指定模块的所有控制器
  * @async
@@ -75,6 +72,12 @@ export function clearConfigCache() {
  * @description
  * 从 modules/{moduleName}/controller 目录加载所有 .js 文件
  * 每个文件会被加载并绑定实例，然后以文件名作为键存储
+ *
+ * 性能优化（P2 #18）：
+ * - 用 Symbol 标记已 bind 过的方法，避免重复 bind 形成嵌套
+ * - ESM 模块缓存导致同一实例可能被多次 loadController，原版每次都重新 bind
+ * - 现在首次 bind 后标记，后续调用直接跳过
+ *
  * @example
  * const controllers = await loadController('api');
  * console.log(controllers.User); // User 控制器实例
@@ -98,8 +101,8 @@ export async function loadController(moduleName) {
     try {
       const module = await import(`file://${filePath}`);
       let instance = module?.default || module;
-      
-      // 绑定实例的所有方法
+
+      // 绑定实例的所有方法（Symbol 幂等，避免重复 bind）
       if (instance && typeof instance === 'object') {
         const proto = Object.getPrototypeOf(instance);
         if (proto) {
@@ -108,12 +111,23 @@ export async function loadController(moduleName) {
               methodName !== "constructor" &&
               typeof instance[methodName] === "function"
             ) {
-              instance[methodName] = instance[methodName].bind(instance);
+              const method = instance[methodName];
+              // 已 bind 过的方法直接跳过（避免重复 bind 嵌套）
+              if (method[BOUND_SYMBOL]) return;
+              // bind 创建新函数，标记后存回实例
+              const bound = method.bind(instance);
+              Object.defineProperty(bound, BOUND_SYMBOL, {
+                value: true,
+                enumerable: false,
+                writable: false,
+                configurable: false,
+              });
+              instance[methodName] = bound;
             }
           });
         }
       }
-      
+
       controller[name] = instance;
     } catch (e) {
       console.error(`加载控制器失败: ${filePath}`, e);

package/middleware/compress.js

@@ -0,0 +1,185 @@
+import zlib from 'zlib';
+
+/**
+ * 响应压缩中间件（零依赖，基于 Node 原生 zlib）
+ * 改进点：
+ * 1. 支持 br / gzip / deflate，按 Accept-Encoding 优先级选择
+ * 2. 仅压缩可压缩文本类型（html/css/js/json/plain/svg+xml）
+ * 3. 跳过 SSE（text/event-stream）和 WebSocket 升级请求
+ * 4. 阈值 1KB，避免小包压缩负收益
+ * 5. 压缩失败自动回退原样输出，不影响请求
+ * 6. chunks 缓冲上限 10MB，超出后 bypass 直接放行不压缩，避免内存爆炸
+ * 7. 拦截 res.write/res.end 后在 finish/close 时恢复，避免泄漏
+ */
+
+// 压缩阈值：响应体 > 1KB 才压缩
+const DEFAULT_THRESHOLD = 1024;
+
+// chunks 缓冲上限：10MB，超出后 bypass 直接放行不压缩
+const MAX_BUFFER_BYTES = 10 * 1024 * 1024;
+
+// 可压缩的 Content-Type 集合（精确匹配，charset 后缀在判断时已剥离）
+const COMPRESSIBLE_TYPES = new Set([
+  'text/html',
+  'text/css',
+  'application/json',
+  'application/javascript',
+  'text/plain',
+  'image/svg+xml',
+]);
+
+/**
+ * 根据 Accept-Encoding 选择最优编码
+ * 优先级：br > gzip > deflate
+ * @param {string} acceptEncoding - 请求头 Accept-Encoding 值
+ * @returns {'br'|'gzip'|'deflate'|null}
+ */
+function pickEncoding(acceptEncoding) {
+  if (!acceptEncoding) return null;
+  const enc = acceptEncoding.toLowerCase();
+  if (enc.includes('br')) return 'br';
+  if (enc.includes('gzip')) return 'gzip';
+  if (enc.includes('deflate')) return 'deflate';
+  return null;
+}
+
+/**
+ * 使用 Node 原生 zlib 同步压缩 Buffer
+ * @param {Buffer} buf - 待压缩数据
+ * @param {'br'|'gzip'|'deflate'} encoding - 压缩编码
+ * @returns {Buffer} 压缩后的 Buffer
+ */
+function compressBuffer(buf, encoding) {
+  switch (encoding) {
+    case 'br':      return zlib.brotliCompressSync(buf);
+    case 'gzip':    return zlib.gzipSync(buf);
+    case 'deflate': return zlib.deflateSync(buf);
+    default:        return buf;
+  }
+}
+
+/**
+ * 创建压缩中间件
+ * @param {Object} [options]
+ * @param {number} [options.threshold=1024] - 压缩阈值（字节），响应体小于该值不压缩
+ * @returns {Function} Express 中间件
+ */
+export function compress(options = {}) {
+  const threshold = options.threshold || DEFAULT_THRESHOLD;
+
+  return (req, res, next) => {
+    // WebSocket 升级请求直接跳过（不适用 HTTP 响应压缩）
+    if (req.headers.upgrade && req.headers.upgrade.toLowerCase() === 'websocket') {
+      return next();
+    }
+
+    const encoding = pickEncoding(req.headers['accept-encoding'] || '');
+    // 客户端不支持任何压缩编码，直接放行
+    if (!encoding) return next();
+
+    // 缓存原方法（bind 避免 this 丢失）
+    const originalEnd = res.end.bind(res);
+    const originalWrite = res.write.bind(res);
+    const chunks = [];
+    let totalSize = 0;
+    let bypassed = false;  // 超过缓冲上限后 bypass 标志
+
+    // 恢复 res.write/res.end 的函数：在 finish/close 时调用，避免拦截函数泄漏
+    const restore = () => {
+      res.write = originalWrite;
+      res.end = originalEnd;
+    };
+
+    // 拦截 res.write：收集 buffer 片段（流式输出场景）
+    res.write = (chunk, ...args) => {
+      if (bypassed) return originalWrite(chunk, ...args);
+      if (chunk) {
+        if (typeof chunk === 'string') {
+          chunk = Buffer.from(chunk, args[0] || 'utf8');
+        }
+        if (Buffer.isBuffer(chunk)) {
+          chunks.push(chunk);
+          totalSize += chunk.length;
+          // 缓冲超限：bypass 直接放行后续 write/end
+          if (totalSize > MAX_BUFFER_BYTES) {
+            console.warn(`[compress] 响应体超过 ${MAX_BUFFER_BYTES} 字节，bypass 直接放行不压缩`);
+            bypassed = true;
+          }
+        }
+      }
+      return true;
+    };
+
+    // 拦截 res.end：收集最后一片 buffer 后决定是否压缩
+    res.end = (chunk, encodingArg) => {
+      if (bypassed) {
+        // bypass 模式：直接走原 end，恢复后退出
+        restore();
+        if (chunk) return originalEnd(chunk, encodingArg);
+        return originalEnd();
+      }
+
+      // res.end 多种签名处理：end() / end(chunk) / end(chunk, encoding) / end(callback)
+      if (chunk) {
+        if (typeof chunk === 'string') {
+          const buf = Buffer.from(chunk, typeof encodingArg === 'string' ? encodingArg : 'utf8');
+          chunks.push(buf);
+          totalSize += buf.length;
+        } else if (Buffer.isBuffer(chunk)) {
+          chunks.push(chunk);
+          totalSize += chunk.length;
+        }
+        // function 类型为 end(callback) 签名，不收集
+      }
+
+      const body = chunks.length ? Buffer.concat(chunks) : Buffer.alloc(0);
+
+      // 取 Content-Type 主类型（去掉 charset 等参数）
+      const contentType = (res.getHeader('Content-Type') || '').toString().split(';')[0].trim().toLowerCase();
+
+      // 不满足压缩条件：原样输出
+      // - 响应体小于阈值
+      // - 非可压缩类型
+      // - SSE（text/event-stream）需要实时推送，不压缩
+      if (
+        body.length < threshold ||
+        !COMPRESSIBLE_TYPES.has(contentType) ||
+        contentType === 'text/event-stream'
+      ) {
+        if (!res.headersSent) {
+          res.setHeader('Content-Length', body.length);
+        }
+        restore();
+        originalEnd(body);
+        return res;
+      }
+
+      // 执行压缩
+      try {
+        const compressed = compressBuffer(body, encoding);
+        // 移除原 Content-Length，避免与压缩后大小不匹配
+        res.removeHeader('Content-Length');
+        res.setHeader('Content-Encoding', encoding);
+        res.setHeader('Vary', 'Accept-Encoding');
+        res.setHeader('Content-Length', compressed.length);
+        restore();
+        originalEnd(compressed);
+      } catch (e) {
+        // 压缩失败：回退原样输出，避免请求中断
+        console.error('[compress] 压缩失败，回退原样输出:', e.message);
+        if (!res.headersSent) {
+          res.setHeader('Content-Length', body.length);
+        }
+        restore();
+        originalEnd(body);
+      }
+      return res;
+    };
+
+    // 响应结束后恢复，防止 res.write/res.end 拦截泄漏到后续中间件复用
+    res.on('finish', restore);
+    res.on('close', restore);
+
+    next();
+  };
+}

package/middleware/cors.js

@@ -1,24 +1,36 @@
-import cors from "cors";
-
-/**
- * CORS 中间件配置
- * 配置跨域资源共享
- */
-
-/**
- * 设置 CORS 中间件
- * @param {Object} app - Express 应用实例
- * @param {Object} _cors - CORS 配置选项
- * @description
- * 为 Express 应用配置 CORS 中间件
- * 支持自定义 CORS 配置选项
- * @example
- * Cors(app, {
- *   origin: '*',
- *   methods: ['GET', 'POST'],
- *   allowedHeaders: ['Content-Type']
- * });
- */
-export const Cors = (app, _cors) => {
-  app.use(cors(_cors));
-};
+import cors from "cors";
+
+/**
+ * CORS 中间件配置
+ * 配置跨域资源共享
+ */
+
+/**
+ * 设置 CORS 中间件
+ * @param {Object} app - Express 应用实例
+ * @param {Object} [_cors={}] - CORS 配置选项
+ * @description
+ * 为 Express 应用配置 CORS 中间件
+ *
+ * 安全改进：
+ * - 默认拒绝跨域（origin=false），避免未配置时全开放
+ * - 默认仅允许 GET/POST 方法
+ * - credentials 默认 false，避免 Cookie 跨域携带
+ * - 业务侧需显式开放时再传入完整 _cors 配置
+ * @example
+ * Cors(app, {
+ *   origin: 'https://example.com',
+ *   methods: ['GET', 'POST', 'PUT', 'DELETE'],
+ *   credentials: true
+ * });
+ */
+export const Cors = (app, _cors = {}) => {
+  const safeOptions = {
+    origin: _cors.origin || false,
+    methods: _cors.methods || ['GET', 'POST'],
+    allowedHeaders: _cors.allowedHeaders || ['Content-Type', 'Authorization'],
+    credentials: !!_cors.credentials,
+    maxAge: _cors.maxAge || 600,
+  };
+  app.use(cors(safeOptions));
+};

package/middleware/header.js

@@ -6,21 +6,16 @@
 /**
  * 设置响应头中间件
  * @param {Object} app - Express 应用实例
- * @param {Object} options - 配置选项
- * @param {string} options.APP_NAME - 应用名称
- * @param {string} options.APP_VERSION - 应用版本
+ * @param {Object} options - 配置选项（保留参数兼容旧调用，不再使用 APP_VERSION）
  * @description
- * 为所有响应添加自定义响应头
- * 包含 Create-By、X-Powered-By、ChanCMS、Server 等头
+ * 为所有响应添加技术栈标识响应头
+ * 保留 ChanCMS 标识，移除版本号防止信息泄露
  * @example
- * setHeader(app, { APP_NAME: 'MyApp', APP_VERSION: '1.0.0' });
+ * setHeader(app, { APP_NAME: 'MyApp' });
  */
-export let setHeader = (app, { APP_NAME, APP_VERSION }) => {
+export let setHeader = (app) => {
   app.use((req, res, next) => {
-    res.setHeader("Create-By", "Chanjs");
     res.setHeader("X-Powered-By", "ChanCMS");
-    res.setHeader("ChanCMS", APP_VERSION);
-    res.setHeader("Server", APP_NAME);
     next();
   });
 };

package/middleware/index.js

@@ -11,4 +11,5 @@ export { setHeader } from "./header.js";
 export { setTemplate } from "./template.js";
 export { Cors } from "./cors.js";
 export { waf } from "./waf.js";
+export { compress } from "./compress.js";
 export { log } from "./log.js";

package/middleware/log.js

@@ -1,5 +1,18 @@
 import morgan from "morgan";
-import { getIp } from "../helper/ip.js";
+import { getIp } from "../utils/ip.js";
+
+/**
+ * morgan 输出格式白名单
+ * 仅允许使用以下格式，避免任意 level 注入导致 morgan 内部异常
+ */
+const ALLOWED_FORMATS = new Set([
+  'chancms',
+  'combined',
+  'common',
+  'dev',
+  'short',
+  'tiny',
+]);
 
 // 自定义 IP 令牌
 morgan.token("ip", (req, res) => {
@@ -35,7 +48,18 @@ morgan.format("chancms", (tokens, req, res) => {
   ].join(" ");
 });
 
+/**
+ * 注册 morgan 日志中间件
+ * @param {Object} app - Express 应用实例
+ * @param {Object} [logger] - 日志配置
+ * @param {string} [logger.level='chancms'] - 日志格式，仅允许白名单内的格式
+ * @description
+ * 安全改进：
+ * - level 必须在白名单内，未配置或非法值默认 'chancms'
+ * - 避免任意字符串传入 morgan 导致格式解析异常
+ */
 export const log = (app, logger) => {
-  const level = logger?.level || "chancms";
-  app.use(morgan(level === "chancms" ? "chancms" : level));
+  const level = logger?.level;
+  const format = ALLOWED_FORMATS.has(level) ? level : 'chancms';
+  app.use(morgan(format));
 };

package/middleware/setBody.js

@@ -12,13 +12,21 @@ import express from "express";
  * @description
  * 为 Express 应用配置请求体解析中间件
  * 支持 JSON、URL 编码和 XML 格式的请求体
+ *
+ * 安全改进：
+ * - urlencoded 也设置 limit 和 parameterLimit，防止参数爆炸攻击
+ * - extended: true 支持嵌套对象（与 qs 行为对齐）
  * @example
  * setBody(app, '10mb');
  */
 let setBody = function (app, JSON_LIMIT) {
   app.use(express.raw({ type: "application/xml", limit: JSON_LIMIT }));
   app.use(express.json({ limit: JSON_LIMIT }));
-  app.use(express.urlencoded({ extended: false }));
+  app.use(express.urlencoded({
+    extended: true,
+    limit: JSON_LIMIT,
+    parameterLimit: 100,
+  }));
 };
 
 export { setBody };

package/middleware/static.js

@@ -25,7 +25,8 @@ export const setStatic = async function (app, statics) {
   if (statics.length > 0) {
     statics.forEach((item) => {
       const { prefix, dir, maxAge } = item;
-      app.use(prefix, express.static(dir, { maxAge: maxAge || 0 }));
+      // dotfile: 'deny' 显式拒绝访问点文件（.env / .git/config 等），避免敏感配置泄漏
+      app.use(prefix, express.static(dir, { maxAge: maxAge || 0, dotfile: 'deny' }));
     });
   }
 };

package/middleware/template.js

@@ -1,10 +1,135 @@
-import "../extend/index.js";
+import template from "art-template";
+import dayjs from "dayjs";
+import relativeTime from "dayjs/plugin/relativeTime.js";
+import "dayjs/locale/zh-cn.js";
+import { createRequire } from 'module';
 import { importjs } from "../global/import.js";
+import { filterXSS } from "../security/xss-filter.js";
+
+const require = createRequire(import.meta.url);
+const { marked } = require('marked');
+
+// ============================================================
+// art-template 过滤器注册（原 extend/art-template.js，合并至此）
+// ============================================================
+dayjs.extend(relativeTime);
+dayjs.locale('zh-cn');
+
+// 禁用原生模板引擎，防止模板直接调用 nodejs 语法
+template.defaults.native = false;
+
+/**
+ * 日期格式化过滤器
+ * @param {Date|string|number} date - 日期对象、日期字符串或时间戳
+ * @param {string} format - 日期格式字符串
+ * @returns {string} 格式化后的日期字符串
+ */
+template.defaults.imports.dateFormat = function (date, format) {
+  if (!date) return "";
+  if (date instanceof Date || typeof date === "string" || typeof date === "number") {
+    date = dayjs(date);
+  } else {
+    return "";
+  }
+  return date.format(format);
+};
+
+/**
+ * 相对时间过滤器（如"刚刚"、"5分钟前"、"3小时前"）
+ * @param {Date|string|number} date - 日期对象、日期字符串或时间戳
+ * @returns {string} 相对时间字符串
+ */
+template.defaults.imports.timeAgo = function (date) {
+  if (!date) return "";
+  const d = dayjs(date);
+  if (!d.isValid()) return "";
+  return d.fromNow();
+};
+
+/**
+ * 字符串截断过滤器
+ * @param {string} str - 原始字符串
+ * @param {number} length - 截断长度，默认10
+ * @returns {string} 截断后的字符串
+ */
+template.defaults.imports.truncate = (str, length = 10) => {
+  return str.length > length ? str.slice(0, length) + "..." : str;
+};
+
+/**
+ * 安全的 JSON 序列化过滤器（模板调试用）
+ * @param {Object} obj - 要序列化的对象
+ * @param {Array} keys - 可选，只返回指定的字段
+ * @returns {string} JSON字符串
+ * @description
+ * 安全改进：用 Object.prototype.hasOwnProperty.call 防止原型污染
+ */
+template.defaults.imports.safeStringify = (obj, keys) => {
+  if (!obj) return 'null';
+  if (keys && Array.isArray(keys) && keys.length > 0) {
+    const filteredObj = {};
+    keys.forEach(key => {
+      // 用原型上的方法调用，避免 obj 重写 hasOwnProperty 导致原型污染
+      if (Object.prototype.hasOwnProperty.call(obj, key)) {
+        filteredObj[key] = obj[key];
+      }
+    });
+    return JSON.stringify(filteredObj, null, 2);
+  }
+  return JSON.stringify(obj, null, 2);
+};
+
+/**
+ * 获取对象所有 key 的过滤器（调试查看数据结构）
+ * @param {Object} obj - 要获取 key 的对象
+ * @param {string} separator - 分隔符，默认换行
+ * @returns {string} 所有 key 的字符串
+ */
+template.defaults.imports.objKeys = (obj, separator) => {
+  if (!obj || typeof obj !== 'object') return '';
+  const sep = separator !== undefined ? separator : '\n';
+  return Object.keys(obj).join(sep);
+};
 
 /**
- * 模板引擎中间件配置
- * 配置 HTML 模板渲染
+ * Markdown 渲染过滤器
+ * 自动检测内容是否为 Markdown 格式，渲染为 HTML
+ * @param {string} content - 文章内容
+ * @param {string} editorType - 编辑器类型，'md' 触发 Markdown 渲染
+ * @param {number} allowScript - 是否允许 script，1 允许
+ * @returns {string} 渲染后的 HTML
+ * @description
+ * 安全改进：
+ * - 渲染后通过 filterXSS 过滤危险标签（script、onerror、onload 等）
+ * - 仅在 allowScript=1 时跳过过滤（受信任内容）
  */
+template.defaults.imports.renderContent = (content, editorType = 'rich', allowScript = 0) => {
+  if (!content || typeof content !== 'string') return content || '';
+
+  let html = content;
+  // Markdown 转换
+  if (editorType === 'md') {
+    try {
+      html = marked.parse(content);
+    } catch (err) {
+      console.error('[renderContent] Markdown 渲染失败:', err.message);
+      html = content;
+    }
+  }
+  // 非 allowScript=1 时通过 filterXSS 完整过滤，移除 script/onevent 等危险内容
+  if (Number(allowScript) !== 1) {
+    try {
+      html = filterXSS(html);
+    } catch (err) {
+      console.error('[renderContent] XSS 过滤失败:', err.message);
+    }
+  }
+  return html;
+};
+
+// ============================================================
+// 模板引擎中间件配置
+// ============================================================
 
 /**
  * 设置模板引擎中间件
@@ -33,5 +158,15 @@ export let setTemplate = (app, config) => {
   });
   app.set("view engine", "html");
   app.set("views", all);
-  app.engine(".html", importjs("express-art-template"));
+  // 引擎加载容错：importjs 抛错时降级为内置默认 engineFn，避免启动失败
+  try {
+    app.engine(".html", importjs("express-art-template"));
+  } catch (err) {
+    console.error('[setTemplate] 加载 express-art-template 失败，降级默认引擎:', err.message);
+    const engineFn = (path, options, callback) => {
+      // 兜底：直接返回模板路径，避免渲染崩溃
+      callback(null, `<pre>Template engine fallback: ${path}</pre>`);
+    };
+    app.engine(".html", engineFn);
+  }
 };