混淆编译策略与配置指南¶

概述¶

本系统采用自动化的混淆编译策略，确保代码安全性的同时，为未来的功能扩展提供便利。通过基于目录的自动发现机制，新增的JS文件会自动包含在混淆列表中，无需手动维护。

混淆编译架构¶

核心组件¶

自动发现机制 (build/obfuscate-and-compress.js)
基于目录的JS文件自动发现
智能排除规则
配置文件驱动的混淆策略
混淆配置文件 (build/obfuscation-config.js)
集中管理混淆规则
多种混淆强度配置
灵活的排除模式
构建脚本
npm run build - 完整混淆+压缩
npm run obfuscate - 仅混淆
npm run compress - 仅压缩

自动发现机制¶

工作原理¶

目录扫描：自动扫描指定目录下的所有JS文件
规则过滤：应用排除规则，过滤不需要混淆的文件
手动指定：支持手动指定特殊处理的文件
智能合并：将自动发现和手动指定的文件合并处理

包含目录¶

includeDirs: [
  'routes',    // 路由文件
  'utils',     // 工具函数
  'scripts',   // 脚本文件
  'config'     // 配置文件
]

排除规则¶

excludePatterns: [
  /\.test\.js$/,    // 测试文件
  /\.spec\.js$/,    // 规范文件
  /debug/,          // 调试文件
  /test/,           // 测试目录
  /example/,        // 示例文件
  /\.min\.js$/      // 已压缩文件
]

混淆配置级别¶

1. 保守混淆 (Conservative)¶

适用场景：开发环境、调试友好
特点：保持代码可读性，最小化兼容性问题
安全级别：基础保护

2. 中等混淆 (Medium)¶

适用场景：生产环境、平衡安全性和性能
特点：增强代码保护，保持良好性能
安全级别：中等保护

3. 高强度混淆 (Aggressive)¶

适用场景：高安全要求环境
特点：最大程度保护代码，可能影响性能
安全级别：最高保护

使用方法¶

基本构建¶

# 完整构建（混淆+压缩）
npm run build

# 仅混淆
npm run obfuscate

# 仅压缩
npm run compress

自定义配置¶

// 在 build/obfuscation-config.js 中修改配置
module.exports = {
  obfuscation: {
    // 选择混淆级别
    level: 'conservative', // 'conservative' | 'medium' | 'aggressive'

    // 自定义混淆规则
    customRules: {
      // 添加新的包含目录
      includeDirs: ['new-utils'],

      // 添加新的排除模式
      excludePatterns: [/\.demo\.js$/]
    }
  }
};

新增文件处理¶

自动包含¶

当在以下目录中添加新的JS文件时，会自动包含在混淆列表中：

routes/ - 路由文件
utils/ - 工具函数
scripts/ - 脚本文件
config/ - 配置文件

手动指定¶

对于特殊文件，可以在配置中手动指定：

manualFiles: [
  'server.js',
  'public/app.js',
  'custom-special-file.js'
]

排除文件¶

如果某个文件不应该被混淆，可以：

重命名文件：使用排除模式中的命名规则
移动到其他目录：将文件移到非包含目录
添加排除模式：在配置中添加新的排除规则

构建输出¶

文件结构¶

dist/
├── routes/          # 混淆后的路由文件
├── utils/           # 混淆后的工具文件
├── scripts/         # 混淆后的脚本文件
├── config/          # 混淆后的配置文件
├── public/          # 前端文件（app.js已混淆）
├── server.js        # 混淆后的服务器文件
└── package.json     # 项目配置

压缩统计¶

构建过程会显示每个文件的压缩率：

混淆并压缩文件: utils/databaseManager.js
✓ 完成: dist/utils/databaseManager.js (压缩率: 51.84%)

最佳实践¶

1. 文件组织¶

将需要混淆的JS文件放在指定目录中
测试文件使用 .test.js 或 .spec.js 后缀
调试文件放在 debug/ 目录中

2. 配置管理¶

定期检查和更新混淆配置
根据安全需求选择合适的混淆级别
保持排除规则的准确性

3. 构建流程¶

开发阶段使用保守混淆
生产环境使用中等或高强度混淆
定期测试混淆后的代码功能

4. 版本控制¶

将混淆配置文件纳入版本控制
记录混淆策略的变更
保持构建脚本的稳定性

故障排除¶

常见问题¶

文件未被混淆
检查文件是否在包含目录中
确认文件名不匹配排除模式
验证文件扩展名为 .js
构建失败
检查文件语法错误
确认依赖关系正确
查看构建日志获取详细错误信息
性能问题
降低混淆级别
减少压缩强度
优化排除规则

调试技巧¶

# 查看发现的文件列表
node -e "const {discoverFilesToObfuscate} = require('./build/obfuscate-and-compress.js'); console.log(discoverFilesToObfuscate());"

# 测试混淆配置
npm run test-obfuscation

更新日志¶

v1.1.65 (2025-08-10)¶

✅ 实现基于目录的自动发现机制
✅ 添加新文件到混淆列表（databaseManager.js, restart.js, replace-db-references.js）
✅ 创建独立的混淆配置文件
✅ 优化构建脚本和错误处理
✅ 添加详细的构建日志和统计信息

未来计划¶

🔄 支持TypeScript文件混淆
🔄 添加混淆强度自动选择
🔄 实现增量构建优化
🔄 支持自定义混淆插件