README.md · Admin/mm_statics

# mm_statics
[中文](./README.md) | [English](./README_EN.md)

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

## 功能特性

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

## 安装

```bash
npm install mm_statics
```

## 快速开始

### 基本使用

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

const app = new Koa();

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

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

### 自定义配置

```javascript
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. 纯静态文件服务

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

### 2. ES6模块转换

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

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

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

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

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

## Vue组件转换特性

### 转换前（Vue单文件组件）

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

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>

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

```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类

#### 构造函数
```javascript
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解析失败（使用回退方案）

## 开发指南

### 本地开发

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

# 安装依赖
npm install

# 运行测试
npm test

# 运行ESLint检查
npx eslint index.js
```

### 测试Vue转换功能

```bash
# 运行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](https://gitee.com/qiuwenwu91/mm_statics/issues)
- 文档: [README_EN.md](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转换逻辑
- 改进错误处理机制
- 更新文档说明

Admin/mm_statics

简介

发行版

贡献者

语言

近期动态

Admin/mm_statics .gitee-modal { width: 500px !important; }

简介

发行版

贡献者

语言

近期动态

搜索帮助

Admin/mm_statics