mm_statics 1.9.0 → 1.9.2

package/lib/static_handle.js

@@ -0,0 +1,823 @@
+const fs = require('fs');
+const path = require('path');
+// 加载 String 原型扩展（fullname/loadText/extname/basename）
+require('mm_helper');
+const { cacheAdmin } = require('mm_cache');
+const { EsToAmd } = require('mm_es6_to_amd');
+const VueSFCCompiler = require('./vue_compiler.js');
+const prettier = require('prettier');
+const { marked } = require('marked');
+
+var vueCompiler = new VueSFCCompiler();
+
+/**
+ * 静态文件处理类
+ */
+class StaticHandle {
+  static config = {
+    // 默认索引文件
+    index: 'index.html',
+    // 默认缓存过期时间
+    max_age: 7200,
+    // 静态文件缓存键前缀
+    prefix: 'static:',
+    // 缓存过期时间
+    cache_age: 7200,
+    // 是否开启缓存
+    cache: true,
+    // 是否开启不可变缓存
+    immutable: true,
+    // 是否隐藏静态文件
+    hidden: false,
+    // 是否格式化静态文件内容
+    format: true,
+    // 是否开启文件扩展名
+    extensions: false,
+    // 是否开启Brotli压缩
+    brotli: false,
+    // 是否压缩静态文件
+    gzip: false,
+    // 静态文件根目录
+    root: './static',
+    // 路由路径
+    path: '/',
+    // 是否编译Vue文件为JS
+    compile_vue: true,
+    // 是否编译Markdown文件为HTML
+    compile_md: true,
+    // 编译Markdown文件时，是否添加引入css和js文件
+    markdown_link: ['/css/common.css', '/css/markdown.css', '/js/markdown.js'],
+    // 需要转换的静态文件路径前缀
+    src_path: '/src',
+    // 需要转换的静态文件扩展名
+    files: ['.js', '.vue', '.html'],
+    // 是否转换ES6模块为AMD模块
+    convert_amd: false,  // 修改为 false，避免 Vue 文件被错误转换为 AMD 格式
+    // 是否开启文件监听
+    watch: false,
+    // 监听的文件扩展名
+    watch_files: ['.js', '.css', '.html', '.vue', '.json', '.md']
+  };
+
+  /**
+   * 初始化静态文件处理类
+   * @param {object} config 配置
+   */
+  constructor(config) {
+    this.config = { ...StaticHandle.config };
+    this.convert = new EsToAmd();
+    this._cache = null;
+    this._watcher = null;
+    this.setConfig(config);
+    this._init();
+  }
+}
+
+/**
+ * 设置配置
+ * @param {object} config 配置
+ */
+StaticHandle.prototype.setConfig = function (config) {
+  Object.assign(this.config, config || {});
+  // 判断root是否绝对路径，不是则改成绝对路径
+  this.config.root = this.config.root.fullname();
+};
+
+/**
+ * 初始化缓存
+ */
+StaticHandle.prototype._init = function () {
+  this._cache = cacheAdmin('os', this.config);
+
+  // 如果配置了文件监听，初始化文件监听器
+  if (this.config.watch && this.config.watch_files.length > 0) {
+    this._initWatcher();
+  }
+};
+
+/**
+ * 检测代码是否包含ES6语法
+ * @param {string} code 代码内容
+ * @returns {boolean} 是否包含ES6语法
+ */
+StaticHandle.prototype._isEs6Code = function (code) {
+  if (!code || typeof code !== 'string') {
+    return false;
+  }
+
+  // ES6语法特征检测
+  const es6_patterns = [
+    /\bimport\s+/g,                 // import语句（支持多行和无分号）
+    /\bexport\s+/g,                 // export语句（支持多行和无分号）
+    /\bclass\s+\w+/g,               // class声明
+    /\bconst\s+\w+/g,               // const声明
+    /\blet\s+\w+/g,                 // let声明
+    /\([^)]*\)\s*=>/g,             // 箭头函数
+    /`[^`]*`/g,                     // 模板字符串
+    /\{[^}]*\}\s*=\s*\w+/g,        // 解构赋值
+    /\bPromise\b/g,                 // Promise对象
+    /\basync\s+function\b/g,        // async函数
+    /\bawait\b/g                    // await关键字
+  ];
+
+  for (let i = 0; i < es6_patterns.length; i++) {
+    if (es6_patterns[i].test(code)) {
+      return true;
+    }
+  }
+
+  return false;
+};
+
+/**
+ * 格式化代码
+ * @param {string} code 代码内容
+ * @param {string} file_type 文件类型
+ * @returns {Promise<string>} 格式化后的代码
+ */
+StaticHandle.prototype._formatCode = async function (code, file_type) {
+  if (!this.config.format || !code || typeof code !== 'string') {
+    return code;
+  }
+
+  try {
+    // 根据文件类型设置prettier配置
+    let parser = 'babel';
+    let plugins = [];
+
+    switch (file_type) {
+      case 'js':
+        parser = 'babel';
+        break;
+      case 'html':
+        parser = 'html';
+        break;
+      case 'vue':
+        parser = 'vue';
+        plugins = [require('prettier/parser-html'), require('prettier/parser-babel')];
+        break;
+      default:
+        parser = 'babel';
+    }
+
+    // prettier.format是异步函数
+    const formatted_code = await prettier.format(code, {
+      parser: parser,
+      plugins: plugins,
+      semi: true,
+      singleQuote: true,
+      trailingComma: 'es5',
+      printWidth: 100,
+      tabWidth: 2,
+      useTabs: false,
+      bracketSpacing: true,
+      arrowParens: 'avoid'
+    });
+
+    return formatted_code;
+  } catch (error) {
+    // 格式化失败时返回原代码
+    console.warn(`格式化代码失败: ${error.message}`);
+    return code;
+  }
+};
+
+// /**
+//  * 处理require模块语句
+//  * @param {string} script 包含require语句的代码
+//  * @returns {string|null} 处理后的代码或null
+//  */
+// StaticHandle.prototype._requireMod = function (script) {
+//   if (script) {
+//     var src = script.between('[', ']');
+//     var imports = src;
+//     var arr = imports.split(',');
+//     var len = arr.length;
+//     for (var i = 0; i < len; i++) {
+//       var s = arr[i];
+//       if (s.endsWith('.vue"')) {
+//         imports = imports.replace(s, '"vue!' + s.trim().trim('"') + '"');
+//       } else if (s.endsWith('.css"')) {
+//         imports = imports.replace(s, '"css!' + s.trim().trim('"') + '"');
+//       } else if (s.endsWith('.html"')) {
+//         imports = imports.replace(s, '"text!' + s.trim().trim('"') + '"');
+//       }
+//     }
+//     return script.replace(src, imports);
+//   }
+//   return null;
+// };
+
+/**
+ * 转换为AMD模块
+ * @param {string} file_type 文件类型
+ * @param {string} text 代码
+ * @returns {Promise<string>} AMD模块代码
+ */
+StaticHandle.prototype._toAmd = async function (file_type, text) {
+  let txt = text;
+  if (file_type === 'js') {
+    // 对JS文件，先检测是否为ES6代码，只有ES6代码才进行转换
+    if (this._isEs6Code(txt)) {
+      let code = this.convert.toAmd(txt);
+      // 处理require模块语句
+      // code = this._requireMod(code);
+      // 添加return语句确保AMD模块正确导出
+      // code = this._addAmdReturn(code);
+      // 格式化代码
+      return await this._formatCode(code, file_type);
+    } else {
+      // 格式化非ES6代码
+      return await this._formatCode(txt, file_type);
+    }
+  } else if (file_type === 'html' || file_type === 'vue') {
+    // 获取html或vue中script标签的代码，将ES6语法的代码转换为AMD模块
+    let match = txt.match(/<script[^>]*>([\s\S]*?)<\/script>/g);
+    if (match) {
+      for (let i = 0; i < match.length; i++) {
+        let script = match[i];
+        // 直接提取script标签内容，避免重复匹配
+        let inner_code = script.replace(/^<script[^>]*>([\s\S]*?)<\/script>$/, '$1').trim();
+        if (inner_code) {
+          // 先检测script标签内的代码是否为ES6语法
+          if (this._isEs6Code(inner_code)) {
+            let amd_code = this.convert.toAmd(inner_code);
+            // 处理require模块语句
+            // amd_code = this._requireMod(amd_code);
+            // // 添加return语句确保AMD模块正确导出
+            // amd_code = this._addAmdReturn(amd_code);
+            // 移除type="module"属性，因为AMD模块不需要这个属性
+            let new_script = script.replace(/type\s*=\s*["']module["']/g, '').replace(inner_code, amd_code);
+            // 清理多余的空格
+            new_script = new_script.replace(/<script\s+>/, '<script>').replace(/<script\s+([^>]+)>/, '<script $1>');
+            txt = txt.replace(script, new_script);
+          }
+          // 如果不是ES6代码，保持原样不进行转换
+        }
+      }
+    }
+  }
+
+  // 格式化代码后返回，确保返回字符串而不是Promise
+  const result = await this._formatCode(txt, file_type);
+  return result;
+};
+
+/**
+   * 编译Vue组件
+   * @param {string} code Vue组件代码
+   * @param {string} filePath 文件路径
+   * @returns {Promise<string>} 可直接调用的JavaScript组件代码
+   */
+StaticHandle.prototype._compileVue = async function (code, filePath = '') {
+  try {
+    // 使用修复后的 Vue 编译器
+    const { code: compiledCode } = await vueCompiler.toJS(code, filePath);
+
+    // Vue 编译后的代码是 JavaScript，应该使用 babel 解析器格式化
+    const result = await this._formatCode(compiledCode, 'babel');
+    return result;
+  } catch (error) {
+    console.error('Vue编译失败:', error);
+    return `console.error('Vue编译失败: ${error.message}');\nexport default { name: 'ErrorComponent' };`;
+  }
+};
+
+/**
+ * 发送文件
+ * 兼容两种上下文：
+ *  - Koa 风格 ctx（具备 ctx.set / ctx.body），以流方式写入 ctx.body
+ *  - mm_web_server 原生 ctx（仅含 ctx.res），直接写 Node 响应并标记 ctx.handled
+ * @param {object} ctx 请求上下文
+ * @param {string} path 文件路径
+ * @returns {Promise<string>} 发送成功返回物理文件路径
+ */
+StaticHandle.prototype._sendFile = async function (ctx, path) {
+  const file_path = this._pathToRoot(path);
+  // 路径越界校验，防止目录穿越
+  if (!this._checkFilePath(file_path)) {
+    throw new Error(`非法路径: ${file_path}`);
+  }
+  const stat = await fs.promises.stat(file_path);
+  if (!stat.isFile()) {
+    throw new Error(`文件不存在: ${file_path}`);
+  }
+  const headers = this._getHeaders(this._getType(path));
+  if (path.endsWith('.md')) {
+    headers['content-type'] = 'text/plain; charset=utf-8';
+  }
+  if (typeof ctx.set === 'function') {
+    // Koa 风格上下文
+    ctx.status = 200;
+    headers['content-length'] = stat.size;
+    ctx.set(headers);
+    ctx.body = fs.createReadStream(file_path);
+    return file_path;
+  }
+  // mm_web_server 原生上下文：直接写响应
+  const res = ctx.res;
+  if (res && !res.headersSent) {
+    const range = this._parseRange(ctx, stat.size);
+    if (range) {
+      headers['content-range'] = `bytes ${range.start}-${range.end}/${stat.size}`;
+      headers['content-length'] = range.end - range.start + 1;
+      res.writeHead(206, headers);
+      fs.createReadStream(file_path, { start: range.start, end: range.end })
+        .on('error', () => res.destroy())
+        .pipe(res);
+    } else {
+      headers['content-length'] = stat.size;
+      headers['accept-ranges'] = 'bytes';
+      res.writeHead(200, headers);
+      fs.createReadStream(file_path)
+        .on('error', () => res.destroy())
+        .pipe(res);
+    }
+    ctx.handled = true;
+  }
+  return file_path;
+};
+
+/**
+ * 校验物理文件路径不越出配置的静态根目录
+ * @param {string} file_path 物理文件路径
+ * @returns {boolean} 合法返回 true
+ */
+StaticHandle.prototype._checkFilePath = function (file_path) {
+  const root_path = path.resolve(this.config.root);
+  const resolved = path.resolve(file_path);
+  return resolved === root_path || resolved.startsWith(root_path + path.sep);
+};
+
+/**
+ * 解析 HTTP Range 请求头
+ * @param {object} ctx 请求上下文
+ * @param {number} total 文件总字节数
+ * @returns {object|null} {start, end} 范围对象，无法解析时返回 null
+ */
+StaticHandle.prototype._parseRange = function (ctx, total) {
+  const headers = (ctx.params && ctx.params.headers) || (ctx.request && ctx.request.headers) || {};
+  const range_header = headers['range'];
+  if (!range_header) return null;
+  const match = /^bytes=(\d*)-(\d*)$/.exec(range_header);
+  if (!match) return null;
+  let start = match[1] ? parseInt(match[1], 10) : null;
+  let end = match[2] ? parseInt(match[2], 10) : null;
+  // 后缀范围，如 bytes=-500 表示取最后 500 字节
+  if (start === null && end !== null) {
+    start = Math.max(0, total - end);
+    end = total - 1;
+  }
+  if (end === null) {
+    end = total - 1;
+  }
+  if (start === null || start >= total || start > end) {
+    return null;
+  }
+  end = Math.min(end, total - 1);
+  return { start, end };
+};
+
+/**
+ * 运行AMD模块
+ * @param {string} path 文件路径
+ * @param {string} file_type 文件类型
+ * @returns {Promise<string>} AMD模块代码
+ */
+StaticHandle.prototype._runAmd = async function (path, file_type) {
+  let type = file_type || this._getType(path);
+  let code = null;
+  let text = `.${path}`.fullname(this.config.root).loadText();
+  if (text) {
+    code = await this._toAmd(type, text);
+  }
+  return code;
+};
+
+/**
+ * 运行Vue组件
+ * @param {string} path 文件路径
+ * @returns {Promise<string>} 编译后的代码
+ */
+StaticHandle.prototype._runVue = async function (path) {
+  let code = null;
+  let file = `.${path}`.fullname(this.config.root);
+  let text = file.loadText();
+  if (text) {
+    code = await this._compileVue(text, file);
+  }
+  return code;
+};
+
+/**
+ * 从Markdown内容中提取第一个一级标题
+ * @param {string} text Markdown文本内容
+ * @returns {string|null} 提取的标题，未找到时返回null
+ */
+StaticHandle.prototype._extractMarkdownTitle = function (text) {
+  if (!text || typeof text !== 'string') {
+    return null;
+  }
+
+  // 匹配一级标题格式：# 标题
+  var title_regex = /^#\s+(.+)$/m;
+  var match = text.match(title_regex);
+
+  if (match && match[1]) {
+    return match[1].trim();
+  }
+
+  return null;
+};
+
+/**
+ * 处理Markdown文件转换
+ * @param {string} path 文件路径
+ * @returns {string|null} 转换后的HTML内容
+ */
+StaticHandle.prototype._runMarkdown = async function (path) {
+  let html = null;
+  let file = `.${path}`.fullname(this.config.root);
+  let text = file.loadText();
+
+  if (text) {
+    try {
+      // 使用marked将markdown转换为HTML
+      let markdown_html = marked.parse(text);
+
+      // 优先从Markdown内容中提取一级标题，后备使用文件名
+      var title_from_content = this._extractMarkdownTitle(text);
+      var title_from_file = path.split('/').pop().replace('.md', '');
+      var title = title_from_content || title_from_file;
+      // 构建外部资源链接
+      let links = '';
+      if (this.config.markdown_link && Array.isArray(this.config.markdown_link)) {
+        this.config.markdown_link.forEach(path => {
+          if (path.endsWith('.css')) {
+            links += `    <link rel="stylesheet" href="${path}">\n`;
+          } else if (path.endsWith('.js')) {
+            links += `    <script src="${path}"></script>\n`;
+          }
+        });
+      }
+
+      // 构建完整的HTML结构
+      html = `<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>${title}</title>
+${links}
+</head>
+<body>
+<div id="app" class="markdown-body">
+${markdown_html}
+</div>
+</body>
+</html>`;
+
+      // 如果启用了格式化，使用prettier格式化完整的HTML
+      if (this.config.format) {
+        try {
+          html = prettier.format(html, {
+            parser: 'html',
+            printWidth: 100,
+            tabWidth: 2
+          });
+        } catch (error) {
+          console.warn('HTML格式化失败，使用原始HTML:', error.message);
+        }
+      }
+    } catch (error) {
+      console.error('Markdown转换错误:', error);
+      return null;
+    }
+  }
+
+  return html;
+};
+
+/**
+ * 返回响应
+ * 兼容两种上下文：
+ *  - Koa 风格 ctx：写入 ctx.body 并通过 ctx.set 设置响应头
+ *  - mm_web_server 原生 ctx：直接写 Node 响应并标记 ctx.handled
+ * @param {object} ctx 请求上下文
+ * @param {string} body 响应体
+ * @param {object} headers 响应头
+ * @returns {object} 响应对象
+ */
+StaticHandle.prototype._return = function (ctx, body, headers) {
+  if (typeof ctx.set === 'function') {
+    ctx.body = body;
+    if (headers) {
+      ctx.set(headers);
+    }
+  } else {
+    const res = ctx.res;
+    if (res && !res.headersSent) {
+      res.writeHead(200, headers || {});
+      res.end(body);
+    }
+    ctx.handled = true;
+  }
+  return { body, headers };
+};
+
+/**
+ * 初始化文件监听器
+ */
+StaticHandle.prototype._initWatcher = function () {
+  try {
+    const chokidar = require('chokidar');
+
+    // 构建监听模式，只监听指定类型的文件
+    const watch_patterns = this.config.watch_files.map(ext =>
+      `${this.config.root}/**/*${ext}`
+    );
+
+    // 监听指定类型的文件
+    this._watcher = chokidar.watch(watch_patterns, {
+      ignored: /(^|[\/\\])\\./, // 忽略隐藏文件
+      persistent: true,
+      ignoreInitial: true // 忽略初始扫描事件
+    });
+
+    // 文件变化时的处理逻辑
+    this._watcher.on('all', (event, file_path) => {
+      this._handleFileChange(event, file_path);
+    });
+  } catch (error) {
+    console.error('文件监听初始化失败:', error.message);
+  }
+};
+
+/**
+ * 处理文件变化事件
+ * @param {string} event 事件类型
+ * @param {string} file_path 文件路径
+ */
+StaticHandle.prototype._handleFileChange = function (event, file_path) {
+  // 构建缓存键（相对于静态目录的路径）
+  const relative_path = file_path.replace(this.config.root, '').replace(/^[\\\/]/, '');
+  const cache_key = this.config.prefix + relative_path;
+
+  // 根据事件类型处理缓存
+  switch (event) {
+    case 'change':
+    case 'add':
+      // 文件修改或新增，删除缓存，下次请求时重新生成
+      this._cache.del(cache_key);
+      break;
+    case 'unlink':
+      // 文件删除，删除缓存
+      this._cache.del(cache_key);
+      break;
+  }
+};
+
+/**
+ * 获取响应头
+ * @param {string} file_type 文件类型
+ * @returns {object} 响应头
+ */
+StaticHandle.prototype._getHeaders = function (file_type) {
+  let headers = {};
+
+  // 缓存控制逻辑
+  if (this.config.max_age > 0) {
+    let cache_control = `max-age=${this.config.max_age}`;
+    if (this.config.immutable) {
+      cache_control += ', immutable';
+    }
+    headers['cache-control'] = cache_control;
+  }
+  switch (file_type) {
+    case 'js':
+      headers['content-type'] = 'application/javascript; charset=utf-8';
+      break;
+    case 'vue':
+      if (this.config.convert_amd) {
+        headers['content-type'] = 'text/html; charset=utf-8';
+      }
+      else if (this.config.compile_vue) {
+        headers['content-type'] = 'application/javascript; charset=utf-8';
+      }
+      else {
+        // 当不编译 Vue 文件时，设置为 JavaScript MIME 类型
+        headers['content-type'] = 'application/javascript; charset=utf-8';
+      }
+      break;
+    case 'html':
+      headers['content-type'] = 'text/html; charset=utf-8';
+      break;
+    case 'css':
+      headers['content-type'] = 'text/css; charset=utf-8';
+      break;
+    case 'md':
+      if (this.config.compile_md) {
+        headers['content-type'] = 'text/html; charset=utf-8';
+      }
+      else {
+        headers['content-type'] = 'text/plain; charset=utf-8';
+      }
+      break;
+    case 'mp3':
+    case 'wav':
+    case 'ogg':
+    case 'm4a':
+      headers['content-type'] = 'audio/mpeg';
+      break;
+    case 'swf':
+      headers['content-type'] = 'application/x-shockwave-flash';
+      break;
+    default:
+      headers['content-type'] = 'text/plain; charset=utf-8';
+      break;
+  }
+  return headers;
+};
+
+/**
+ * 设置缓存
+ * @param {string} path 文件路径（包含查询参数）
+ * @param {object} ret 响应体和响应头
+ */
+StaticHandle.prototype._setCache = async function (path, ret) {
+  // 使用完整路径（包含查询参数）作为缓存键
+  await this._cache.set(this.config.prefix + path, ret, this.config.cache_age);
+};
+
+/**
+ * 获取文件类型
+ * @param {string} path 文件路径
+ * @returns {string} 文件类型（不含点号）
+ */
+StaticHandle.prototype._getType = function (path) {
+
+  // 使用mm_expand提供的extname方法获取扩展名
+  const ext = path.extname().toLowerCase();
+  if (ext) {
+    return ext.slice(1); // 去掉点号
+  }
+
+  // 备用方法：处理多扩展名情况
+  const basename = path.basename();
+  const parts = basename.split('.');
+
+  // 如果文件名包含多个点号，取最后一个作为扩展名
+  if (parts.length > 1) {
+    return parts[parts.length - 1];
+  }
+
+  return ''; // 无扩展名
+};
+
+/**
+ * 获取缓存
+ * @param {string} path 文件路径（包含查询参数）
+ * @returns {object} 响应体和响应头
+ */
+StaticHandle.prototype._getCache = async function (path) {
+  // 使用完整路径（包含查询参数）作为缓存键
+  return await this._cache.get(this.config.prefix + path);
+};
+
+/**
+ * 删除缓存
+ * @param {string} path 文件路径（包含查询参数）
+ */
+StaticHandle.prototype._delCache = async function (path) {
+  await this._cache.del(this.config.prefix + path);
+};
+
+/**
+ * 处理缓存逻辑
+ * @param {string} url 完整URL
+ * @param {object} ctx Koa上下文对象
+ * @returns {boolean} 是否命中缓存
+ */
+StaticHandle.prototype._handleCache = async function (url, ctx) {
+  if (!this.config.cache) return false;
+
+  let ret = await this._getCache(url);
+  if (ret) {
+    this._return(ctx, ret.body, ret.headers);
+    return true;
+  }
+  return false;
+};
+
+/**
+ * 处理文件编译逻辑
+ * @param {string} path 文件路径
+ * @returns {string|null} 编译后的内容
+ */
+StaticHandle.prototype._handleFileCompile = async function (path) {
+  let { src_path, compile_md, files, compile_vue, convert_amd } = this.config;
+  if (compile_md && path.extname() === '.md') {
+    return await this._runMarkdown(path);
+  } else if (!path.startsWith(src_path)) return null;
+
+  let file_type = this._getType(path);
+
+  if (convert_amd && file_type !== 'md' && files.includes('.' + file_type)) {
+    return await this._runAmd(path, file_type);
+  }
+  else if (compile_vue && file_type === 'vue') {
+    return await this._runVue(path);
+  }
+  return null;
+};
+
+/**
+ * 处理编译后的文件响应
+ * @param {string} url 完整URL
+ * @param {string} path 文件路径
+ * @param {string} body 响应体
+ * @param {object} ctx Koa上下文对象
+ */
+StaticHandle.prototype._handleCompiledResp = async function (url, path, body, ctx) {
+  let file_type = this._getType(path);
+  // 只有当启用了Markdown转换时，才将markdown文件类型设置为HTML
+  if (file_type === 'md' && this.config.compile_md) {
+    file_type = 'html';
+  }
+  let headers = this._getHeaders(file_type);
+  let ret = this._return(ctx, body, headers);
+
+  // 只有当缓存启用时才设置缓存
+  if (this.config.cache) {
+    await this._setCache(url, ret);
+  }
+};
+
+/**
+ * 获取真实路径
+ * @param {string} path 文件路径
+ * @returns {string} 真实路径
+ */
+StaticHandle.prototype._getRealPath = function (path) {
+  return path;
+}
+
+/**
+ * 将路由路径转换为物理路径
+ * @param {string} path 文件路径
+ * @returns {string} 根路径
+ */
+StaticHandle.prototype._pathToRoot = function (path) {
+  return ("." + path).fullname(this.config.root);
+}
+
+/**
+ * 主处理函数
+ * 兼容两种上下文：
+ *  - Koa 风格 ctx：使用 ctx.path / ctx.url
+ *  - mm_web_server 原生 ctx：从 ctx.params 读取 path，发送文件后标记 ctx.handled
+ * @param {object} ctx 请求上下文
+ * @param {Function} next 跳过当前处理函数
+ */
+StaticHandle.prototype.main = async function (ctx, next) {
+  let p = ctx.path || (ctx.params && ctx.params.path) || '';
+  let url = ctx.url || p; // 使用完整URL（包含查询参数）
+  if (p.indexOf('.') === -1) {
+    await next();
+    return '';
+  }
+  let path = this._getRealPath(p);
+
+  // 检查缓存
+  if (await this._handleCache(url, ctx)) {
+    return this._pathToRoot(path);
+  }
+
+  // 处理文件编译
+  let body = await this._handleFileCompile(path);
+  if (body) {
+    await this._handleCompiledResp(url, path, body, ctx);
+    return this._pathToRoot(path);
+  }
+
+  // 直接发送文件
+  try {
+    return await this._sendFile(ctx, path);
+  }
+  catch {
+    await next();
+  }
+  return '';
+};
+
+/**
+ * 关闭文件监听器
+ */
+StaticHandle.prototype.closeWatcher = function () {
+  if (this._watcher) {
+    this._watcher.close();
+    this._watcher = null;
+  }
+};
+
+module.exports = StaticHandle;