@51jbs/webpack-spec-plugin

Webpack 插件，用于自动检查代码规范、性能和安全问题，并生成详细的 HTML 报告

✨ 特性

📝 代码规范检查 - 57 项全面检查

• 🎨 Vue2 规范检查 - 13 项专项检查（组件命名、Props、生命周期等）
• 🔧 JavaScript 规范检查 - 8 项语法检查（禁用 var、严格相等、模板字符串等）
• 📁 文件命名规范 - 5 项检查（Vue 组件、JS 文件、测试文件等）
• 🔤 变量命名检查 - 6 项检查（常量、变量、类名、布尔值等）
• 📥 导入规范检查 - 6 项检查（循环依赖、未使用导入、重复导入等）
• 📝 注释规范检查 - 3 项检查（JSDoc、TODO/FIXME、大段注释代码）
• 🎭 事件规范检查 - 9 项专项检查（Vue2 事件、JavaScript 事件）
• 🛡️ 空指针防护检查 - 9 项安全检查（属性访问、数组、API 响应）
• 🎯 边界处理规范检查 - 11 项边界检查（循环、递归、除零、分页等）
• 🔥 最佳实践检查 - 10 项检查（深拷贝、console、var、Promise链等）
• 📧 消息提示一致性 - 7 项检查（统一消息提示用法）
• 🔒 接口安全检查 - 8 项检查（错误处理、响应校验、超时设置等）
• ✅ 表单验证检查 - 9 项检查（验证规则、必填项、提交检查等）
• 📦 依赖检查 - 6 项检查（重复导入、未使用导入、路径优化等）

⚡ 性能与安全检查

• ⚡ 性能检查 - 图片/JS/CSS 文件大小预算
• 🔒 安全检查 - XSS 风险、eval 使用、敏感信息泄露
• 💧 内存泄漏检查 - 定时器、事件监听器、全局变量污染

📊 报告与工具

• 📊 HTML 报告 - 详细的修复方案 + 代码对比 + 优先级标签
• 🚀 增量检查 - 只检查 Git 变更文件，提高效率
• 💾 文件缓存 - MD5 哈希缓存，避免重复检查
• 🎯 Git Hooks - pre-commit 自动检查

📚 文档

• 👋 快速开始 - 5 分钟上手
• ✨ 功能特性 - 完整功能列表
• 📖 Vue2 开发规范 - 1160 行详细指南
• 📖 JavaScript 开发规范 - 1200 行详细指南
• 🎭 事件规范 - 9 项事件处理规范
• 🛡️ 空指针防护规范 - 9 项防空检查
• 📊 HTML 报告 - 报告功能详解
• ✅ 真实项目验证 - 生产项目验证报告
• 🧪 生产环境评估 - 综合评分 94.05/100
• 📝 更新日志 - 版本更新记录

📦 安装

npm install @51jbs/webpack-spec-plugin --save-dev

⚙️ 快速配置

webpack.config.js

const SpecPlugin = require('@51jbs/webpack-spec-plugin')

module.exports = {
  plugins: [
    new SpecPlugin({
      // 检查模式：'incremental' | 'full'
      mode: 'incremental',
      
      // 严格程度：'normal' | 'strict'
      severity: 'normal',
      
      // 启用的规则
      rules: {
        naming: true,              // 文件命名检查
        comments: true,            // 注释规范检查
        performance: true,         // 性能检查
        imports: true,             // 导入规范检查
        variableNaming: true,      // 变量命名检查
        memoryLeak: true,          // 内存泄漏检查
        security: true,            // 安全检查
        vue: true,                 // Vue2 规范检查（13 项）
        javascript: true,          // JavaScript 规范检查（8 项）
        event: true,               // 事件规范检查（9 项）
        nullSafety: true,          // 空指针防护检查（9 项）
        boundary: true,            // 边界处理规范检查（11 项）
        bestPractice: true,        // 最佳实践检查（10 项）
        messageConsistency: true,  // 消息提示一致性（7 项）
        apiSafety: true,           // 接口安全检查（8 项）
        formValidation: true,      // 表单验证检查（9 项）
        dependencyCheck: true      // 依赖检查（6 项）
      },
      
      // 性能预算
      performanceBudget: {
        maxImageSize: 500,  // KB
        maxJsSize: 300,
        maxCssSize: 100
      },
      
      // HTML 报告（生成在 .spec-cache 目录）
      htmlReport: true,
      reportPath: '.spec-cache/spec-report.html'
    })
  ]
}

🚀 快速使用

1. 本地开发

npm run dev
# 自动检查变更文件

2. 查看报告

open .spec-cache/spec-report.html

3. 生产构建

npm run build
# 全量检查 + 生成报告

📊 报告示例

v2.0 增强版报告

报告包含：

1. 📝 整体总结 - 检查概览 + 问题分类 + 优先级建议
2. 🏷️ 优先级标签 - P0/P1/P2 明确标识
3. 🔧 详细修复方案 - 分步骤修复指导
4. 💡 代码对比 - 修改前/修改后对比展示
5. 📊 统计图表 - 规则分布可视化

支持的问题类型：

• ✅ 内存泄漏（定时器/全局变量）
• ✅ 安全风险（XSS 攻击）
• ✅ 性能问题（图片过大）
• ✅ 导入规范（缺少扩展名）
• ✅ Vue2 规范（组件命名/Props/生命周期）
• ✅ JavaScript 规范（var/严格相等/模板字符串）
• ✅ 事件规范（事件命名/监听器清理）
• ✅ 空指针防护（属性访问/API响应/DOM操作）
• ✅ 边界处理（循环/递归/除零/分页）
• ✅ 最佳实践（深拷贝/console/var等）
• ✅ 消息提示一致性
• ✅ 接口安全检查
• ✅ 表单验证检查
• ✅ 依赖检查

✅ 真实项目验证

mall-portal-front 项目

项目规模：

• 总文件数：1,452 个
• JavaScript/Vue：633 个
• 代码规模：~50,000 行

发现问题：

• 错误：8 个
• 警告：20 个
• 总计：28 个

问题分类：

• 内存泄漏：6 个
• 安全风险：1 个
• 性能问题：9 个
• 导入规范：12 个

优化价值：

• 图片优化：8-10 MB (减少 67-75%)
• 加载速度：提升 50-70%
• 首屏时间：8s → 2-3s

查看完整验证报告

📝 修复示例

内存泄漏 - 定时器

问题代码：

export default {
  mounted() {
    setInterval(() => {
      this.updateTime()
    }, 1000)
  }
}

修复方案：

export default {
  data() {
    return { timer: null }
  },
  mounted() {
    this.timer = setInterval(() => {
      this.updateTime()
    }, 1000)
  },
  beforeUnmount() {
    if (this.timer) {
      clearInterval(this.timer)
      this.timer = null
    }
  }
}

查看更多示例

Vue2 规范 - 组件命名

问题代码：

<script>
export default {
  name: 'Todo'  // ❌ 单个单词，与 HTML 元素易冲突
}
</script>

修复方案：

<script>
export default {
  name: 'TodoItem'  // ✅ 多个单词，符合规范
}
</script>

JavaScript 规范 - 禁止 var

问题代码：

var userName = 'Alice'  // ❌ 使用 var，有变量提升问题

修复方案：

const userName = 'Alice'  // ✅ 使用 const，更安全

接口安全检查

问题代码：

// ❌ 缺少错误处理
axios.get('/api/user').then(res => {
  this.user = res.data
})

修复方案：

// ✅ 添加错误处理
axios.get('/api/user')
  .then(res => {
    this.user = res.data
  })
  .catch(err => {
    console.error('获取用户信息失败:', err)
    this.$message.error('获取用户信息失败')
  })

查看完整规范文档

🎯 特色功能

1. 不污染项目目录

所有生成文件都在 .spec-cache 目录中：

.spec-cache/
  ├── spec-report.html    # HTML 报告
  └── check-cache.json    # 检查缓存

已自动添加到 .gitignore，不影响版本控制。

2. 智能缓存机制

• 基于 MD5 哈希缓存
• 未变更文件跳过检查
• 提高检查效率 ~85%

3. 优先级系统

• P0 - 立即修复（错误级别）
• P1 - 尽快修复（安全、内存）
• P2 - 计划修复（规范问题）

🛠️ 开发

# 安装依赖
npm install

# 编译 TypeScript
npm run build

# 运行测试
npm test

📝 许可证

MIT © 2025

👥 贡献

欢迎提交 Issue 和 Pull Request！

🔗 相关链接

• 📚 文档中心
• 🚀 快速开始
• ✅ 真实验证
• 📊 HTML 报告