Frontend Code Audit

English | 简体中文

一个全面的前端代码质量审计工具，支持 React/Vue/Next.js 项目。

✨ 特性

• 🔍 代码重复检测 - 自动识别重复代码（≥2次），建议提取公共组件
• 📁 文件组织检查 - 验证业务组件、共享组件、Hooks 的位置是否正确
• 📝 命名规范 - 强制 camelCase/PascalCase，避免过度业务化命名
• 🎨 DOM/CSS 优化 - 减少无用嵌套，优先使用 Flexbox
• 📦 Import 规范 - 强制使用 @/ 别名路径
• 💬 注释标准 - 单行 //，多行 /** */，优先行尾注释
• 🔒 TypeScript - 禁止 any，强制类型定义
• ⚡ 性能检查 - 检测 inline functions、缺失的 keys、不必要的 re-render
• 🔗 依赖管理 - 未使用依赖、循环依赖检测
• 🛡️ 安全检查 - eval()、XSS 风险、硬编码敏感信息

📦 安装

作为 OpenClaw/Claude Code Skill

# 使用 npx skills
npx skills add xueyangeng/frontend-code-audit

# 或手动克隆
git clone https://github.com/xueyangeng/frontend-code-audit.git ~/.agents/skills/frontend-code-audit

独立使用（仅脚本）

git clone https://github.com/xueyangeng/frontend-code-audit.git
cd frontend-code-audit
bash scripts/audit.sh /path/to/your/project

🚀 使用方法

1. 在 AI 对话中使用

支持的 AI 工具：

• OpenClaw
• Claude Code
• Codex CLI
• Gemini CLI
• 其他支持 AgentSkills 的工具

# 在 AI 对话中输入：
/frontend-code-audit /path/to/project

# 自动修复模式
/frontend-code-audit /path/to/project --auto-fix

# JSON 输出（CI/CD）
/frontend-code-audit /path/to/project --format json

2. 直接运行脚本

# 完整审计
bash scripts/audit.sh /path/to/project

# 带自动修复
bash scripts/audit.sh /path/to/project --auto-fix

# JSON 格式输出
bash scripts/audit.sh /path/to/project --format json

📊 审计维度

1. 代码重复检测

• 相似度 ≥80% 的代码块
• 提供公共组件/工具函数提取建议

2. 文件组织

src/
├── components/       # 复用组件（≥3次使用）
├── features/         # 业务功能模块
│   └── user/
│       ├── components/  # 功能专属组件
│       └── hooks/       # 功能专属 hooks
├── hooks/            # 全局 hooks
├── utils/            # 纯函数工具
└── types/            # 全局类型定义

3. 命名规范

• camelCase: 变量、函数（onClick, handleSubmit）
• PascalCase: 组件、类（UserCard, Button）
• SCREAMING_SNAKE_CASE: 常量（MAX_RETRY）
• 语义化命名: 通用而非特定业务（onClick ✅ vs onSendPost ❌）

4. DOM/CSS 优化

• 检测多余嵌套（>4层）
• 标记过度使用 position: absolute/fixed
• 建议用 Flexbox 替代定位

5. Import 路径

// ❌ 相对路径地狱
import { Button } from '../../../components/Button';

// ✅ 别名路径
import { Button } from '@/components/Button';

6. 注释规范

// ✅ 单行注释
const total = price + tax;

// ✅ 多行注释（复杂逻辑）
/**
 * 计算复利，包含阶梯利率
 * 第1档: 0-10k @ 2.5%
 * 第2档: 10k-50k @ 3.2%
 */
const calculateInterest = (amount) => {};

// ✅ 行尾注释（优先）
const total = price * (1 + TAX_RATE); // 含税总价

7. 魔法字符串

// ❌ 硬编码字符串
if (user.role === 'admin') {}

// ✅ 常量定义
const USER_ROLES = {
  ADMIN: 'admin',
  USER: 'user',
} as const;

if (user.role === USER_ROLES.ADMIN) {}

8. TypeScript 质量

• 禁止 any（使用 unknown 或具体类型）
• Props 必须有类型定义
• 避免过度使用类型断言

9. React 性能

• 检测 inline functions（导致不必要 re-render）
• 缺失的 key prop
• useEffect 依赖项检查
• 建议使用 React.memo/useMemo/useCallback

10. 依赖问题

• 未使用的 imports
• 循环依赖
• 重复依赖（monorepo）

📄 输出报告

生成 frontend-audit-report.md，包含：

• 执行摘要: 质量评分（0-100）、问题总数
• 分类问题: 按审计维度分组
• 优先级排序: P0（关键）→ P3（优化）
• 代码示例: Before/After 对比
• 可自动修复项: 列出 --auto-fix 可处理的问题

⚙️ 配置

在项目根目录创建 .frontend-audit.json:

{
  "rules": {
    "maxDomNesting": 4,
    "maxComponentLines": 300,
    "duplicateThreshold": 0.8,
    "enforceAliasImports": true
  },
  "ignore": [
    "**/node_modules/**",
    "**/*.test.tsx",
    "**/dist/**"
  ]
}

🔧 CI/CD 集成

GitHub Actions

# .github/workflows/code-quality.yml
name: Code Quality

on: [push, pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install Dependencies
        run: |
          npm install -g jscpd depcheck madge
      
      - name: Run Frontend Audit
        run: |
          bash scripts/audit.sh . --format json > audit-results.json
      
      - name: Check Quality Gate
        run: |
          SCORE=$(jq '.score' audit-results.json)
          if [ "$SCORE" -lt 70 ]; then
            echo "❌ Quality score too low: $SCORE"
            exit 1
          fi
          echo "✅ Quality score: $SCORE"
      
      - name: Upload Report
        uses: actions/upload-artifact@v3
        with:
          name: audit-report
          path: frontend-audit-report.md

🛠️ 依赖工具

审计脚本使用以下工具（自动安装）：

• jscpd - 代码重复检测
• depcheck - 未使用依赖检测
• madge - 循环依赖检测
• ESLint - 代码规范检查（如果项目已配置）
• TypeScript - 类型检查（如果项目使用 TS）

📚 参考文档

• 代码质量标准 - 完整的前端代码规范
• ESLint 配置 - 推荐的 ESLint 规则
• 中文文档 - 详细中文说明

🤝 配合使用

如果你使用 Impeccable Skills，可以组合使用：

# 1. 先审计
/frontend-code-audit /path/to/project

# 2. 性能优化
/optimize [目标文件]

# 3. 细节润色
/polish [目标组件]

# 4. 边界情况加固
/harden [目标功能]

🔄 自动修复

支持安全的自动修复：

• ✅ Import 路径转换（../.. → @/）
• ✅ 注释格式统一
• ✅ 未使用 import 清理
• ✅ ESLint 可修复的问题

# 预览修复（不实际改动）
/frontend-code-audit /path/to/project --auto-fix --dry-run

# 应用修复
/frontend-code-audit /path/to/project --auto-fix

📝 示例输出

# Frontend Code Audit Report

**Generated:** 2026-03-30T15:20:00Z

## Executive Summary

- **Total Issues:** 47
- **Quality Score:** 76/100
- **Code Duplication:** 8 instances
- **File Organization:** 12 issues
- **Unused Dependencies:** 5
- **Circular Dependencies:** 2

## Priority 0 (Critical)
- Fix circular dependencies in `features/user` → `features/auth`

## Priority 1 (High)
- Move `hooks/UserCard.tsx` to `features/user/components/`
- Remove unused dependencies: `lodash`, `moment`
...

🐛 常见问题

Q: 为什么我的 hooks 被标记为错误位置？

A: 只有以 use 开头的文件才应该放在 hooks/ 目录。组件应该放在 components/ 或 features/*/components/。

Q: 如何禁用某些检查？

A: 在项目根目录创建 .frontend-audit.json 配置文件，设置相应规则。

Q: 自动修复安全吗？

A: --auto-fix 只执行安全操作（import 路径、注释格式等）。建议先用 --dry-run 预览。

Q: 支持哪些框架？

A: React、Vue、Next.js、Remix、Nuxt 等现代前端框架。

📄 许可证

MIT License

👨‍💻 作者

耿学岩 - @xueyangeng

耿上了科技创始人

🌟 致谢

本项目参考了以下优秀实践：

• Impeccable Skills - 设计技能框架
• OpenClaw - AI 代理平台
• Anthropic Claude - AI 辅助开发

---

如果这个工具对你有帮助，请给个 ⭐️ Star！