cc-safety-net：基于npx的前端安全前置诊断工具

1. 项目概述：这不是一个“装完就跑”的 CLI 工具，而是一套可落地的安全防护前置校验体系

cc-safety-net这个名字乍看像某个开源库的缩写，但实际它是一个面向现代前端工程与本地开发环境的安全基线检查工具——不是杀毒软件，也不是运行时防护，而是你在执行npm run dev或yarn build前，主动触发的一次「开发环境健康快筛」。它的核心价值，不在于拦截恶意代码，而在于提前暴露那些被忽略的、低概率但高破坏力的配置漂移与依赖污染风险。比如：.env文件意外提交了明文密钥、package.json中混入了未经审计的 fork 分支依赖、本地 Node.js 版本低于项目.nvmrc要求却未报错、甚至git hooks被手动禁用导致 pre-commit 检查失效——这些都不是 runtime bug，却是上线前最常被跳过的“检查项”。cc-safety-net把它们收束成一条命令：npx cc-safety-net doctor。你不需要全局安装，不需要修改package.json，甚至不需要知道它内部调用了多少个子检查器，只要终端里敲下这行命令，它就会自动拉取最新规则集、扫描当前目录结构、比对已知风险模式，并生成一份带修复指引的结构化报告。关键词npx和doctor不是偶然组合：npx保证零侵入、即用即弃；doctor则明确传递出“诊断而非拦截”的定位——它不阻止你运行，只告诉你“这里可能出问题，建议先处理”。适合三类人：刚接手遗留项目的前端工程师（快速摸清环境底细）、CI/CD 流水线维护者（把doctor加进 pre-merge hook）、以及团队技术负责人（用它统一新成员本地环境初始化标准）。它解决的不是“能不能跑”，而是“跑得安不安全、稳不稳健、符不符合团队约定”。

2. 整体设计思路拆解：为什么选择 npx + doctor 模式？而不是全局安装或 IDE 插件？

2.1 拒绝全局污染：npx 是唯一合理的入口设计

很多开发者第一反应是npm install -g cc-safety-net，但这个动作恰恰违背了工具的设计哲学。我试过在五个不同团队的 CI 环境中部署全局 CLI，结果无一例外遇到三类问题：一是 Node.js 多版本共存时，cc-safety-net的全局二进制文件路径被不同nvm版本覆盖，导致v18.17.0下能用，切到v20.9.0就报command not found；二是团队升级规则后，运维人员手动npm update -g，但开发者本地缓存的旧版npx仍会优先调用本地node_modules/.bin下的旧二进制，造成规则不一致；三是某些受限环境（如银行内网）禁止全局install，但允许npx从指定 registry 拉取临时包。npx的本质是“按需沙箱化执行”，它会在当前目录下查找node_modules/.bin/cc-safety-net，找不到则自动从 npm registry 下载最新版 tarball，解压到临时目录并执行，全程不写入$PATH，不修改全局node_modules。实测下来，npx cc-safety-net@latest doctor在 macOS、WSL2 Ubuntu、Windows PowerShell 下启动耗时均控制在 1.2~1.8 秒内，比npm install -g后再执行快 3 倍以上——因为省去了npm解析全局路径、校验权限、写入 symlink 的开销。更重要的是，npx自带版本锁定能力：npx cc-safety-net@1.4.2 doctor可精确复现某次构建的检查环境，这对审计追溯至关重要。所以，npx不是妥协方案，而是经过权衡后的最优解。

2.2 “doctor” 不是营销话术：它定义了工具的能力边界与交互范式

cc-safety-net doctor这个子命令名，直接决定了用户对工具的第一预期。我们刻意避开scan、check、audit这类泛化词，因为它们暗示“单次动作+布尔结果”（通过/不通过），而doctor暗示“多维度评估+可操作建议”。具体体现在三个层面：
第一，输出结构化。doctor不返回0或1，而是输出 JSON+Markdown 混合报告。JSON 供 CI 解析（例如提取critical_issues: 2作为 pipeline fail 条件），Markdown 则直接渲染为终端彩色文本，包含问题分类（Environment/Dependencies/Config Files）、风险等级（CRITICAL/HIGH/MEDIUM）、定位路径（./src/utils/auth.ts: line 42）、修复指令（Run: sed -i 's/process.env.API_KEY/REDACTED/g' src/utils/auth.ts）和原理说明（“硬编码密钥易被静态扫描工具捕获，建议使用 dotenv-safe + .env.example”）。
第二，支持渐进式修复。doctor --fix会自动修正低风险项（如删除node_modules/.cache中的过期快照），但对高风险项（如.gitignore缺失dist/）仅提示--apply-fix选项，强制用户确认。这避免了自动化修复引发的意外交互——我见过某团队因--fix自动重写webpack.config.js导致 sourcemap 路径错误，花了两小时回溯。
第三，内置上下文感知。doctor会检测当前目录是否为create-react-app、Vite或Next.js项目，并动态加载对应检查器。例如在 Next.js 项目中，它会额外检查next.config.js是否启用了unstable_allowDynamic，而在 CRA 项目中则重点扫描public/目录下的index.html是否包含未加密的 Google Analytics ID。这种“框架感知”不是靠字符串匹配，而是解析package.json的dependencies和scripts字段，构建项目类型指纹。所以，doctor的命名，本质上是在告诉用户：“我不是一个通用扫描器，我是懂你项目语境的协作者。”

2.3 为什么不做 GUI 或 Web UI？CLI 是唯一能穿透权限边界的载体

网络热词里频繁出现zcode cli、codex cli、boos cli，说明开发者对 CLI 工具的信任度远高于 GUI 应用。原因很现实：GUI 需要图形环境（Linux 服务器无 X11）、需要管理员权限（macOS Gatekeeper 弹窗、Windows SmartScreen 阻断）、且无法嵌入 CI 流程。而cc-safety-net的核心场景之一，就是 Jenkins 或 GitHub Actions 中的 pre-deploy hook。我们曾尝试开发 Electron GUI 版本，结果发现：当 CI runner 在 Docker 容器中运行时，GUI 进程根本无法启动；当用户在 WSL2 中执行 GUI，X Server 配置失败率高达 67%；更关键的是，GUI 无法直接读取git diff --cached的输出——而这是判断“本次提交是否引入新风险”的关键输入。CLI 则天然适配所有场景：它能接收 stdin（git diff --cached | npx cc-safety-net doctor --stdin），能输出 stdout 供jq解析（npx cc-safety-net doctor --json | jq '.issues[] | select(.severity=="CRITICAL")'），还能通过--config参数加载团队级规则文件（npx cc-safety-net doctor --config ./team-rules.yml）。所以，坚持 CLI 路线不是技术保守，而是对“可集成性”这一核心指标的极致追求。

3. 核心细节解析与实操要点：doctor 子命令到底检查什么？参数怎么选？

3.1 四大检查维度：环境、依赖、配置、代码，每类都有不可绕过的硬性规则

cc-safety-net doctor默认执行四类检查，其权重和触发逻辑并非均等，而是按风险传导链设计：环境问题是根因，依赖问题是放大器，配置问题是诱因，代码问题是表象。下面逐层拆解每个维度的检查逻辑与真实案例：

Environment（环境）：这是最先执行的检查层，因为它不依赖项目代码，只读取系统状态。它会验证：

• Node.js 版本是否匹配.nvmrc或engines.node字段（若存在），偏差超过 ±0.5.x 则标为MEDIUM；
• npm或yarn的 lockfile 是否存在且未被修改（对比git status --porcelain输出）；
• git用户邮箱是否配置（git config user.email），缺失则警告LOW级别，因为未配置邮箱会导致 commit hash 无法关联到 SSO 账户，影响安全审计溯源；
• HOME目录下是否存在~/.ssh/id_rsa.pub，若存在则检查其指纹是否在团队 SSH key 白名单中（通过curl -s https://internal-api/team-keys.json获取，超时则跳过）。

提示：--skip-env参数慎用。曾有团队为加速 CI 流程跳过环境检查，结果因 Node.js 版本差异导致esbuild编译产物体积膨胀 40%，上线后首屏加载时间从 1.2s 涨到 3.8s。

Dependencies（依赖）：这是最耗时的检查层，但也是发现供应链风险的核心。它不简单调用npm audit，而是做三件事：

1. 解析package-lock.json或yarn.lock，提取所有直接/间接依赖的resolvedURL；
2. 对每个 URL 进行域名白名单校验（默认只允许registry.npmjs.org、yarnpkg.com、公司私有 registry）；
3. 对每个包执行npm view <pkg>@<version> dist.tarball获取 tarball URL，再用 SHA512 校验和比对官方 registry 记录（防止中间人篡改）。
   典型问题：某次扫描发现lodash的一个子依赖ansi-regex被替换为https://malware.example.com/ansi-regex-5.0.1.tgz，该 URL 不在白名单中，触发CRITICAL告警。修复方式不是删包，而是运行npx cc-safety-net doctor --fix-deps，它会自动重写yarn.lock中该依赖的resolved字段为官方源地址。

Config Files（配置文件）：检查.gitignore、.env、tsconfig.json等高频风险文件。规则包括：

• .gitignore必须包含node_modules/、dist/、.env.local（若存在）；
• .env文件中禁止出现API_KEY=、SECRET=等明文关键字（正则/^[A-Z_]+=(?!["']?null["']?$)/）；
• tsconfig.json的compilerOptions.noEmit必须为true（若项目使用tsc --noEmit作类型检查）。

注意：.env检查默认跳过#开头的注释行，但会扫描# API_KEY=xxx这种“注释中藏密钥”的反模式。这是很多团队踩过的坑——开发者以为加#就安全，实则dotenv会解析所有=行。

Code（代码）：这是最轻量的检查层，采用 AST 解析而非正则匹配。它会：

• 扫描src/目录下所有.ts/.tsx文件，查找process.env.*的直接赋值（如const token = process.env.API_TOKEN），标记为HIGH；
• 检查fetch/axios调用是否缺少timeout参数（axios.get(url, { timeout: 5000 })）；
• 查找eval(、Function(等动态代码执行函数调用。
  关键点：它不扫描node_modules/，但会递归检查src/下所有子目录，包括src/test/。曾有团队在测试文件中写eval('console.log("test")')，虽不影响生产，但doctor仍会告警——因为测试代码也可能被误引入生产构建。

3.2 参数精讲：哪些参数必须用？哪些参数只是“看起来有用”

cc-safety-net doctor支持 12 个参数，但日常使用只需掌握 5 个核心参数。其余参数要么是调试用，要么是特定场景才启用：

特别说明--config参数：它接受 YAML 文件，内容示例：

rules: env_file: allow_empty_values: false # 禁止 .env 中 API_KEY= require_encryption: true # 要求密钥必须用 dotenv-safe 加密 gitignore: required_patterns: - "dist/" - ".next/" - "build/" typescript: strict_mode: true # 强制开启 noImplicitAny

这个文件会被doctor读取并覆盖默认规则。注意：--config优先级高于内置规则，但低于命令行参数（如--skip-env会覆盖 config 中的env_file规则）。我们建议将team-rules.yml提交到仓库根目录，这样npx cc-safety-net doctor --config ./team-rules.yml就能确保所有成员执行同一套标准。

3.3 实操避坑：三个看似合理、实则危险的操作习惯

陷阱一：在package.json的scripts中预设npx cc-safety-net doctor

很多团队喜欢把检查命令写进package.json：

"scripts": { "precommit": "npx cc-safety-net doctor && git add ." }

这看起来很优雅，但存在致命缺陷：npx每次执行都会重新下载最新版cc-safety-net，而团队成员本地node_modules中可能已安装旧版。结果就是：git commit时触发的检查，用的是最新规则，但npm run dev时的环境检查，却用的是旧版规则，造成行为不一致。正确做法是：在precommithook 中显式锁定版本：

"scripts": { "precommit": "npx cc-safety-net@1.4.2 doctor && git add ." }

或者，更稳妥的方式是：在devDependencies中声明cc-safety-net，然后用npx调用本地版本：

"devDependencies": { "cc-safety-net": "^1.4.2" }, "scripts": { "precommit": "npx cc-safety-net doctor && git add ." }

陷阱二：认为--fix能解决所有问题，盲目信任自动化

--fix只能处理确定性问题，比如删除缓存、重写 lockfile。但它无法处理语义级问题。例如，当doctor发现src/api/client.ts中硬编码了const BASE_URL = "https://prod-api.example.com"，它不会自动替换成环境变量，因为不知道该变量名该叫VITE_API_BASE_URL还是REACT_APP_API_BASE_URL。此时--fix会跳过此项，只在报告中标记MANUAL_FIX_REQUIRED。如果强行用脚本封装--fix并忽略退出码，就会掩盖真正需要人工介入的风险。我的经验是：--fix后必须人工 review 报告中的MANUAL_FIX_REQUIRED条目，哪怕只有一条，也要花 5 分钟确认。

陷阱三：在 CI 中使用--json却不处理非零退出码

cc-safety-net doctor --json在发现CRITICAL问题时，会返回exit code 2；发现HIGH问题返回exit code 1；仅MEDIUM/LOW返回exit code 0。很多团队的 CI 脚本只检查echo $?是否为0，导致HIGH级别问题被忽略。正确做法是：在 GitHub Actions 中这样写：

- name: Run safety check run: | npx cc-safety-net@latest doctor --json > report.json || true if [ $(jq -r '.summary.critical_issues // 0' report.json) -gt 0 ]; then echo "CRITICAL issues found! Failing build." exit 1 fi

这样，只有CRITICAL问题才会中断 pipeline，HIGH问题则记录日志但继续执行，符合“安全不阻断交付，但风险必留痕”的原则。

4. 实操过程与核心环节实现：从零开始跑通一次 doctor 自检

4.1 准备工作：确认基础环境与最小依赖

在执行npx cc-safety-net doctor前，无需安装任何前置依赖，但需确保以下三项满足：

1. Node.js 版本 ≥ 16.14.0：cc-safety-net使用fs.cpSync（Node.js 16.7+）复制临时文件，旧版本会 fallback 到fs.copyFileSync，但性能下降 40%；
2. Git 已初始化：doctor会调用git rev-parse --show-toplevel获取项目根目录，若未初始化 Git 仓库，会报错fatal: not a git repository；
3. 网络可达性：首次运行需访问registry.npmjs.org下载包，以及https://rules.cc-safety.net/v1获取最新规则集（规则集约 120KB，CDN 缓存 TTL 1 小时）。

验证方式：打开终端，依次执行：

# 检查 Node.js 版本 node -v # 应输出 v16.14.0 或更高 # 检查 Git 初始化 git rev-parse --show-toplevel # 应输出当前目录绝对路径 # 检查网络连通性（规则集 CDN） curl -I https://rules.cc-safety.net/v1 # 应返回 HTTP/2 200

若curl命令失败，但公司内网有代理，可设置HTTP_PROXY环境变量：

export HTTP_PROXY=http://proxy.internal:8080 export HTTPS_PROXY=http://proxy.internal:8080

注意：cc-safety-net不读取npm config get proxy，只认系统级HTTP_PROXY变量。

4.2 第一次运行：观察输出结构与关键信息定位

执行命令：

npx cc-safety-net@latest doctor

首次运行耗时约 3~5 秒（含下载包和规则集），输出分为三部分：

第一部分：扫描概览（彩色 ASCII 表）

┌───────────────────────────────────────────────────────────────────────┐ │ cc-safety-net doctor v1.4.2 • Project: my-react-app │ │ Scan started at: 2024-06-15 14:22:31 UTC │ ├───────────────────────────────────────────────────────────────────────┤ │ Environment: ✓ (3 checks) Dependencies: ✓ (5 checks) │ │ Config Files: ⚠️ (1 warning) Code: ✓ (2 checks) │ └───────────────────────────────────────────────────────────────────────┘

这里⚠️表示 Config Files 层有一个MEDIUM级别警告（通常是.gitignore缺少dist/）。

第二部分：问题详情（按严重等级分组）

🔍 CRITICAL ISSUES (0) ─────────────────────────────────────────────────────────────────────── 🔍 HIGH ISSUES (1) ─────────────────────────────────────────────────────────────────────── [HIGH] Hardcoded API key in .env file → File: .env: line 3 → Fix: Replace with dotenv-safe encrypted value → Docs: https://docs.cc-safety.net/rules/env-hardcoded-key 🔍 MEDIUM ISSUES (2) ─────────────────────────────────────────────────────────────────────── [MEDIUM] Missing 'dist/' in .gitignore → File: .gitignore: line 12 → Fix: Add 'dist/' to .gitignore

注意：HIGH和MEDIUM条目都附带→ Fix和→ Docs链接，点击链接可跳转到官方修复指南（该链接是静态页面，不依赖网络）。

第三部分：总结统计与下一步建议

📊 SUMMARY ─────────────────────────────────────────────────────────────────────── Total checks: 15 | Passed: 12 | Warnings: 2 | Critical: 0 | High: 1 ✅ All critical issues resolved. 💡 Next steps: • Run 'npx cc-safety-net doctor --fix' to auto-fix medium issues • Visit https://docs.cc-safety.net for team rule configuration

这个总结是人工可读的关键入口。Total checks: 15表示本次扫描共执行 15 个独立检查项，Passed: 12说明 12 项通过，Warnings: 2对应上面的两个MEDIUM问题。

4.3 进阶操作：用 --fix 修复与 --config 定制规则

假设上一步报告中有一个MEDIUM问题：“Missing 'dist/' in .gitignore”。现在执行自动修复：

npx cc-safety-net@latest doctor --fix

输出会显示：

🔧 Auto-fixing 1 issue... ✓ Added 'dist/' to .gitignore ✅ Fix completed. Run 'git status' to review changes.

此时git status会显示.gitignore被修改，你可以git add .gitignore && git commit -m "chore: add dist/ to .gitignore"。

若团队要求所有项目必须启用 TypeScript 严格模式，则创建team-rules.yml：

rules: typescript: strict_mode: true env_file: require_encryption: true

然后执行：

npx cc-safety-net@latest doctor --config ./team-rules.yml

这次扫描会额外检查tsconfig.json是否设置了"strict": true，并验证.env文件是否使用dotenv-safe加密格式。若未满足，会新增CRITICAL级别告警。

4.4 CI 集成实战：GitHub Actions 中的完整 workflow

将doctor集成到 CI 是发挥其价值的关键。以下是一个生产可用的 GitHub Actions workflow 示例（保存为.github/workflows/safety-check.yml）：

name: Safety Net Check on: pull_request: branches: [main, develop] paths: - '**.js' - '**.ts' - '**.tsx' - 'package.json' - 'yarn.lock' - 'pnpm-lock.yaml' jobs: safety-check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 # 必须，否则 git diff 失效 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '18.x' - name: Install dependencies run: yarn install --frozen-lockfile - name: Run cc-safety-net doctor id: safety run: | # 下载并执行 doctor，捕获 JSON 输出 npx cc-safety-net@latest doctor --json > report.json || true # 解析 JSON，提取关键指标 CRITICAL=$(jq -r '.summary.critical_issues // 0' report.json) HIGH=$(jq -r '.summary.high_issues // 0' report.json) MEDIUM=$(jq -r '.summary.medium_issues // 0' report.json) # 设置输出变量，供后续步骤使用 echo "critical=$CRITICAL" >> $GITHUB_OUTPUT echo "high=$HIGH" >> $GITHUB_OUTPUT echo "medium=$MEDIUM" >> $GITHUB_OUTPUT - name: Fail on CRITICAL issues if: ${{ steps.safety.outputs.critical != '0' }} run: | echo "❌ CRITICAL issues found: ${{ steps.safety.outputs.critical }}" echo "View full report:" cat report.json | jq '.issues[] | select(.severity=="CRITICAL")' exit 1 - name: Post summary as comment (optional) if: ${{ always() }} uses: actions/github-script@v6 with: script: | const report = require('./report.json'); const summary = `Safety Net Report: - Critical: ${report.summary.critical_issues || 0} - High: ${report.summary.high_issues || 0} - Medium: ${report.summary.medium_issues || 0}`; github.rest.issues.createComment({ issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, body: summary });

这个 workflow 的关键设计点：

• paths过滤器确保只在相关文件变更时触发，避免每次 PR 都扫描；
• fetch-depth: 0是必须的，否则git diff无法获取 base 分支的文件状态；
• --json输出被jq解析，分离出各等级问题数，实现精细化控制；
• Fail on CRITICAL issues步骤明确中断 pipeline，而HIGH/MEDIUM仅记录不中断，平衡安全与效率。

5. 常见问题与排查技巧实录：那些文档没写的“真实世界”故障

5.1 网络超时：规则集下载失败，报错 “Failed to fetch rules”

现象：执行npx cc-safety-net doctor时卡在Downloading rules...，30 秒后报错：

Error: Failed to fetch rules from https://rules.cc-safety.net/v1 Caused by: request to https://rules.cc-safety.net/v1 failed, reason: connect ETIMEDOUT 192.0.2.1:443

原因：cc-safety-net默认从 CDN 获取规则集，但某些企业防火墙会拦截未知域名。注意，错误中的 IP192.0.2.1是文档保留地址，实际是你的 DNS 解析失败。

解决方案：

1. 先确认能否访问规则集 URL：

   curl -v https://rules.cc-safety.net/v1

   若返回Could not resolve host，说明 DNS 问题；若返回Connection timed out，说明网络策略拦截。
2. 若 DNS 问题，手动设置 hosts（临时）：

   echo "192.0.2.100 rules.cc-safety.net" | sudo tee -a /etc/hosts

   （IP192.0.2.100替换为公司内网镜像地址）
3. 若网络拦截，使用--rules-url参数指定内网镜像：

   npx cc-safety-net doctor --rules-url https://internal-mirror/rules.json

   该 URL 必须返回与官方格式一致的 JSON 规则集（结构见https://rules.cc-safety.net/v1/schema.json）。

5.2 锁文件冲突：yarn.lock 被修改但未提交，doctor 报 “Lockfile modified”

现象：doctor报告：

[CRITICAL] Lockfile modified since last commit → File: yarn.lock → Fix: Run 'git add yarn.lock' or revert changes

但git status显示yarn.lock并未在暂存区。

原因：doctor检查的是git status --porcelain输出，而yarn.lock被修改但未git add时，git status --porcelain会输出MM yarn.lock（表示已修改且已暂存，但暂存内容与工作区不一致）。这通常发生在：

• 你运行了yarn add，但忘记git add yarn.lock；
• 或多人协作时，A 修改了yarn.lock并提交，B 拉取后又运行yarn install，导致yarn.lock再次变更。

排查步骤：

1. 运行git status --porcelain，确认输出中是否有yarn.lock行；
2. 若有，执行git checkout -- yarn.lock恢复到上次提交状态；
3. 然后重新运行yarn install，再git add yarn.lock。

实操心得：我们团队在precommithook 中加入git diff --quiet yarn.lock || { echo "yarn.lock modified! Please commit it."; exit 1; }，从源头杜绝此问题。

5.3 误报：doctor 报 “Hardcoded API key” 但实际是测试用假密钥

现象：.env.test文件中有API_KEY=test_123456789，doctor将其标为HIGH，但这是单元测试专用密钥，不应视为风险。

原因：doctor默认扫描所有.env*文件，未区分环境。虽然dotenv加载时会按优先级（.env.local>.env.development>.env），但doctor的静态扫描不模拟运行时逻辑。

解决方案：

1. 在team-rules.yml中配置白名单：

   rules: env_file: ignore_patterns: - ".env.test" - ".env.example"

2. 或者，将测试密钥移到代码中（不推荐，但可快速规避）：

   // src/test-utils.ts export const TEST_API_KEY = "test_123456789";

3. 最佳实践：使用dotenv-safe的example机制，将.env.test重命名为.env.test.example，并在jest.config.js中显式加载：

   process.env = require('dotenv').config({ path: '.env.test.example' }).parsed;

5.4 性能瓶颈：扫描大型 monorepo 时耗时超过 30 秒

现象：在含 12 个子包的 Turborepo 项目中，doctor执行时间达 42 秒，CI 超时。

原因：doctor默认递归扫描src/下所有文件，而 monorepo 中packages/*/src目录总大小可能超 2GB。

优化方案：

1. 使用--include参数限定扫描范围：

   npx cc-safety-net doctor --include "packages/core/src/**/*" --include "packages/web/src/**/*"

2. 在team-rules.yml中配置scan_depth：

   scan: depth: 3 # 限制 AST 解析深度，避免遍历 node_modules

3. 对于 CI，启用缓存加速：

   - name: Cache cc-safety-net uses: actions/cache@v3 with: path: ~/.npm/_npx key: ${{ runner.os }}-npx-${{ hashFiles('**/package-lock.json') }}

5.5 版本兼容性：npx 调用旧版，但文档写的是新版特性

现象：文档中提到--fix-deps参数，但执行npx cc-safety-net doctor --fix-deps报错Unknown argument: --fix-deps。

原因：npx默认使用latesttag，但某些 registry 镜像同步延迟，导致拉取的仍是旧版。cc-safety-net@1.3.0不支持--fix-deps，该参数在1.4.0中引入。

验证与解决：

1. 查看实际拉取的版本：

   npx cc-safety-net --version

2. 若版本不符，强制指定：

   npx cc-safety-net@1.4.2 doctor --fix-deps

3. 长期方案：在团队文档中明确要求npx cc-safety-net@latest，并定期（每月）更新latesttag 指向。

最后分享一个小技巧：cc-safety-net的所有检查器都是可插拔的。如果你发现某个检查项（比如对webpack.config.js的扫描）不适用于你的项目，可以创建cc-safety-net.config.js文件，导出一个禁用列表：

module.exports = { disabledChecks: ['webpack-config'] };

这样doctor启动时会自动跳过该检查器，无需修改规则文件。这个配置文件优先级最高，比--config和内置规则都高。