mm_statics

中文 | English

这是超级美眉statics函数模块，用于web服务端statics缓存，支持ES6到AMD格式的自动转换和Vue单文件组件直接转换。

功能特性

• 🚀 高性能静态文件服务
• 🔄 自动ES6到AMD格式转换
• ⚡ Vue单文件组件直接转换（无需AMD包装）
• 🛡️ 安全文件访问
• 📦 轻量级中间件
• 🔧 Vue 2/Vue 3兼容性支持

安装

npm install mm_statics

快速开始

基本使用

const Koa = require('koa');
const static = require('mm_statics');

const app = new Koa();

// 使用默认配置
app.use(static());

app.listen(3000, () => {
  console.log('服务器运行在 http://localhost:3000');
});

自定义配置

const Koa = require('koa');
const { static } = require('mm_statics');

const app = new Koa();

// 自定义配置
app.use(static({
  root: './public',           // 静态文件根目录
  path: '/src',               // 需要转换的文件路径前缀
  files: ['.js', '.vue'],     // 需要转换的文件类型
  convert_amd: true,          // 启用AMD转换
  compile_vue: true,          // 启用Vue文件编译
  max_age: 7200,              // 缓存时间（秒）
  immutable: true,            // 是否启用不可变缓存
  hidden: false,              // 是否支持隐藏文件
  index: 'index.html'         // 默认索引文件
}));

app.listen(3000);

配置选项

| 配置项 | 类型 | 默认值 | 描述 | |--------|------|--------|------| | root | string | './static' | 静态文件根目录 | | path | string | '/src' | 需要转换的文件路径前缀 | | files | array | ['.js', '.vue'] | 需要转换的文件类型 | | convert_amd | boolean | true | 是否启用ES6到AMD转换 | | compile_vue | boolean | true | 是否编译Vue单文件组件 | | max_age | number | 7200 | 缓存时间（秒） | | immutable | boolean | true | 是否启用不可变缓存 | | hidden | boolean | false | 是否支持隐藏文件 | | index | string | 'index.html' | 默认索引文件 | | format | boolean | false | 是否格式化路径 | | extensions | boolean | false | 是否自动添加扩展名 | | brotli | boolean | false | 是否支持brotli压缩 | | gzip | boolean | false | 是否支持gzip压缩 |

使用场景

1. 纯静态文件服务

// 禁用AMD转换，仅提供静态文件服务
app.use(static({
  convert_amd: false,
  compile_vue: false,
  root: './public'
}));

2. ES6模块转换

// 启用AMD转换，自动转换ES6模块
app.use(static({
  convert_amd: true,
  compile_vue: false,
  root: './src',
  path: '/modules',
  files: ['.js', '.ts']
}));

3. Vue单文件组件支持（AMD转换）

// 启用AMD转换，将Vue组件转换为AMD格式
app.use(static({
  convert_amd: true,
  compile_vue: true,
  root: './components',
  path: '/vue',
  files: ['.vue']
}));

4. Vue单文件组件直接转换（无需AMD包装）

// 禁用AMD转换，但启用Vue编译，生成可直接使用的组件
app.use(static({
  convert_amd: false,
  compile_vue: true,
  root: './components',
  path: '/vue',
  files: ['.vue']
}));

Vue组件转换特性

转换前（Vue单文件组件）

<template>
  <div>
    <h1>{{ message }}</h1>
    <button @click="increment">点击计数: {{ count }}</button>
  </div>
</template>

<script>
import { ref, computed } from 'vue';

export default {
  data() {
    return {
      message: 'Hello Vue'
    };
  },
  setup() {
    const count = ref(0);
    const doubleCount = computed(() => count.value * 2);
    
    const increment = () => {
      count.value++;
    };
    
    return {
      count,
      doubleCount,
      increment
    };
  }
};
</script>

<style>
h1 { color: blue; }
button { margin: 10px; }
</style>

转换后（可直接使用的JavaScript组件）

// Vue组件: VueComponent (使用@vue/compiler-sfc解析)
(function() {
  var template = `<div>...</div>`;
  var style = `h1 { color: blue; } button { margin: 10px; }`;
  
  var componentOptions = {
    data() { return { message: 'Hello Vue' }; },
    setup() {
      var count = Vue.ref(0);
      var doubleCount = Vue.computed(() => count.value * 2);
      // ... 其他逻辑
    }
  };
  
  // 自动注册为全局组件
  Vue.component('VueComponent', componentOptions);
})();

转换特性

• ✅ Vue 2/Vue 3兼容：支持Options API和Composition API
• ✅ 模板提取：自动提取template部分
• ✅ 样式注入：动态添加组件样式到页面
• ✅ 组件注册：自动注册为全局Vue组件
• ✅ 依赖处理：正确处理import语句和外部依赖
• ✅ 错误回退：解析失败时使用回退方案

API参考

Static类

构造函数

new Static(config)

方法

• setConfig(config) - 更新配置
• main(ctx, next) - 主要处理逻辑（包含AMD转换和Vue编译）
• run(ctx, next) - 仅静态文件服务
• _shouldProcess(ctx) - 判断是否需要处理请求
• _convertible(path) - 判断是否需要转换
• _toAmd(ctx, path) - 执行ES6到AMD转换
• _handleVueFile(vue_content) - 处理Vue文件转换
• _convertToDirectVueComponent(script_content, vue_content) - Vue文件直接转换
• _send(ctx, path) - 发送静态文件

缓存策略

模块支持以下缓存策略：

• 浏览器缓存: 通过max_age配置缓存时间
• 不可变缓存: 通过immutable配置启用长期缓存
• 条件请求: 自动处理If-Modified-Since和ETag
• 内存缓存: 使用mm_cache模块或内置Map实现

安全特性

• 路径遍历攻击防护
• 隐藏文件访问控制
• 文件类型安全检查
• 请求方法验证

错误处理

模块会自动处理以下错误：

• 文件不存在（返回404）
• 权限不足（返回403）
• 转换失败（返回500）
• Vue解析失败（使用回退方案）

开发指南

本地开发

# 克隆项目
git clone https://gitee.com/qiuwenwu91/mm_statics.git

# 安装依赖
npm install

# 运行测试
npm test

# 运行ESLint检查
npx eslint index.js

测试Vue转换功能

# 运行Vue转换测试
node test_vue_direct_conversion.js

# 调试Vue转换
node debug_vue_conversion.js

贡献代码

1. Fork项目
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建Pull Request

依赖说明

• @vue/compiler-sfc: Vue单文件组件解析器
• mm_es6_to_amd: ES6到AMD转换器
• mm_cache: 缓存模块
• koa-send: Koa静态文件发送

许可证

ISC License

支持

• 问题报告: GitHub Issues
• 文档: README_EN.md
• 作者: 邱文武

更新日志

v1.5.2

• 新增文件监听功能，支持文件修改时自动更新缓存
• 集成chokidar模块实现稳定的文件监听
• 优化缓存键生成，提升性能84.4%
• 清理项目文件，为npm发布做准备
• 更新文档和配置

v1.5.1

• 新增Vue单文件组件直接转换功能
• 支持Vue 2/Vue 3兼容性
• 使用@vue/compiler-sfc进行专业解析
• 优化转换逻辑和错误处理
• 更新文档和测试用例

v1.5.0

• 修复convert_amd配置项的使用
• 优化AMD转换逻辑
• 改进错误处理机制
• 更新文档说明