fallow-rs/fallow · 上手攻略

  • 仓库：fallow-rs/fallow
  • 链接：https://github.com/fallow-rs/fallow
  • 分类：Developer · Code Analysis / Code Quality
  • 作者：Tom
  • 更新：2026-10-01

§0 速览

维度 详情
定位 TypeScript / JavaScript 代码库智能分析工具（静态分析）
核心能力 代码健康度、复杂度热点、循环依赖、重复代码、未使用代码、架构边界、样式漂移
技术栈 Rust + Oxc 解析器，无需 TypeScript 编译器或 Node.js 运行时
性能 20,558 文件的 Next.js monorepo 分析约 2.95 秒（fallow 2.100.0）
集成 CLI、GitHub Actions、VS Code、LSP、MCP
许可证 MIT

§1 是什么

Fallow 是用 Rust 编写的代码库智能分析工具，MIT 许可证，无需配置、开箱即用，将整个代码库作为一张依赖图来理解：模块、导出、依赖、函数、样式 token 全部纳入分析范围，一次运行同时输出健康度评分、复杂度热点、重复代码、未使用文件/导出/依赖、架构边界违规等结果。

它的核心特点：静态分析 + 无需 Node.js + 零配置 + 快。与 ESLint、Prettier 等工具关注代码风格不同，Fallow 关注的是代码结构的质量——哪里难改、哪里架构漂移、哪里有重复、哪里没人用。

§2 解决什么问题

  1. 代码库质量黑盒化：项目规模扩大后，开发者不清楚哪些模块是高风险区、哪些代码已经无人使用，只能靠记忆或人工排查。
  2. 代码审查缺乏客观依据：PR 审查时很难量化"这段代码改起来风险有多大"，Fallow 用数据说话——复杂度圈复杂度、健康度评分、循环依赖路径。
  3. 技术债务累积不被感知：未使用导出、重复逻辑、架构违规等小问题日积月累成技术债务，Fallow 一次扫描即可量化这些债务。
  4. AI Coding Agent 需要结构感知：当 Claude Code / Cursor 等 AI 工具在代码库中工作时，它们缺乏对整体架构的理解，Fallow 的 MCP 工具让 AI Agent 能够"看到"代码库的结构边界和风险点。

§3 快速安装

方式一：npx 即时运行（推荐尝鲜）

npx fallow

方式二：项目本地安装

npm install --save-dev fallow
# 或
yarn add -D fallow
# 或
pnpm add -D fallow

方式三：Docker

docker pull fallowrs/fallow
docker run --rm -v $(pwd):/app fallowrs/fallow

方式四：Homebrew（macOS / Linux）

brew install fallow-rs/tap/fallow

方式五：cargo install

cargo install fallow-cli

⚠️ 注意：npm 包包含 fallow、fallow-lsp、fallow-mcp 三个启动器；其他安装方式请参考官方安装指南。

§4 核心用法

4.1 一键全面扫描

npx fallow

输出：健康度评分 + 重复代码 + 未使用文件/导出，一次搞定。

4.2 PR 审查专用（仅报告本次变更引入的问题）

npx fallow audit --base HEAD~15

⚠️ 重要特性：默认只报告本次变更引入的新问题，不计算历史积压（--gate all 可强制全部检查）。这意味着 CI 失败只因为本次 PR 引入了新问题，不会因为项目本身积累的债务而阻断合并。

示例输出：

● Circular dependencies (24)
 packages/vitest/src/runtime/runner/artifact.ts (6 cycles)
 → run.ts → context.ts → artifact.ts

── Duplication ────────────────────────────────────
⚠ 185 lines (0.2%) duplicated across 6 files

● High complexity functions (28)
 packages/vitest/src/runtime/runner/run.ts
 :566 runTest CRITICAL
 32 ! cyclomatic 47 ! cognitive 203 lines

✗ dead code: 68 issues · complexity: 28 findings · duplication: 7 clone groups · 73 changed files
 audit gate excluded 98 inherited findings (run with --gate all to enforce)

4.3 代码健康度评估

npx fallow health --score

输出 0–100 的健康分数，分数越低表示技术债务越严重，附扣分最多项及 git churn、代码 owner 信息。

4.4 死代码检测与自动修复

# 预览要删除的内容（不实际删除）
npx fallow dead-code --trace src/api.ts:client  # 追踪某个导出是否真的无人使用

# 预览自动修复
npx fallow fix --dry-run

# 确认后执行
npx fallow fix

⚠️ 警告：fallow fix 会直接修改文件系统，强烈建议先用 --dry-run 确认影响范围。

4.5 样式漂移检测

npx fallow health --css

检测 CSS / CSS-in-JS 中混用 px、rem、em 等单位的问题，帮助维持设计系统一致性。

4.6 代码重复检测

npx fallow dupes

检测 JS、TS、CSS、Vue、Svelte、Astro 组件中的重复代码逻辑。

4.7 可视化地图

npx fallow viz

生成交互式 HTML 地图，提供健康度、重复代码、架构、未使用代码等多个镜头切换。

4.8 类型感知精确分析（可选）

npx fallow --type-aware

使用 Oxc 类型感知分析，消除接口和基类产生的误报（需要额外数据下载，约 3 秒额外开销）。

4.9 Monorepo 指定包

npx fallow --workspace @company/package-name

仅分析指定包的代码，避免全仓库扫描。

4.10 AI Agent MCP 集成

npx fallow agent install

为 Claude Code、Cursor 等 AI 编码工具安装 MCP 工具，Agent 可以调用结构化的 fallow_* 工具来理解代码库。

§5 典型适用场景

  1. PR Gate 自动化：在 CI 中跑 fallow audit --base main，失败时阻止合并，确保新代码不引入复杂度热点或死代码。
  2. 代码重构优先级排序：用 fallow health 对全仓库模块打分，先修分数最低的几个模块，降低重构风险。
  3. 大型 Monorepo 治理：在 Turborepo / Nx monorepo 中跑 Fallow，建立代码质量基线，持续追踪新增技术债务。
  4. AI Coding Agent 辅助：Cursor / Claude Code 通过 MCP 调用 Fallow，让 AI 在修改代码前先理解依赖关系和边界。
  5. 清理未使用代码：发布前跑 fallow fix --dry-run，批量移除零引用导出和依赖。
  6. 设计系统一致性检查：fallow health --css 检测样式漂移，保持 UI 一致性。

§6 坑与注意

  1. ⚠️ 不替代 ESLint：Fallow 不做代码风格检查，需要配合 ESLint / Prettier 使用——风格问题找 ESLint，结构问题找 Fallow。
  2. ⚠️ 循环依赖检查对动态 import 敏感：如果代码中有大量动态 import()，可能产生噪音；不过 Fallow 默认行为已较保守。
  3. ⚠️ 安全检查是可选功能：默认关闭，启用方式：fallow security，按可达入口点排列安全候选风险。
  4. ⚠️ 健康分数 ≠ 代码有 bug：高分（接近 100）表示静态结构良好，但不等于代码逻辑正确——它是风险指标，不是缺陷指标。
  5. ⚠️ --type-aware 有额外开销：在大型代码库上类型感知分析耗时更长（约 3 秒），CI 中使用需评估对构建时间的影响。
  6. ⚠️ monorepo 只支持 npm/yarn/pnpm workspace：不自动识别 NX/Turborepo 虚拟 workspace，需要通过 --workspace 手动指定包名。
  7. ⚠️ 实时覆盖功能是付费云端功能：本地分析无法获取生产运行时数据来计算覆盖率，需要 Fallow Cloud 订阅。
  8. ⚠️ similar-code 使用本地下载模型：该功能会下载一个本地模型（约一次下载），使用前需确认网络和磁盘条件。
  9. ⚠️ 输出格式需选对：默认是 CLI 彩色输出；JSON 格式需加 --json 标志；CI 中使用建议显式指定格式。
  10. ⚠️ audit 只报告新增问题：返回 0 findings 可能是因为本次变更没问题，也可能是历史债务未纳入统计，需要注意解读。

§7 与同类对比

工具 语言 分析范围 许可证 性能 AI Agent 集成
Fallow Rust 健康度/复杂度/死代码/重复/架构/样式 MIT 20K 文件 ~3s MCP + VS Code
ESLint JS 代码风格/部分质量 MIT 取决于规则数 无原生
SonarQube Java 全面（质量/安全/覆盖率） 商业+开源 较重 无原生
Codacy — 代码质量/风格 SaaS 云端 无原生
GitHub CodeQL 多语言 安全+质量 GitHub 所有 中等 无原生

核心差异：Fallow 是静态代码结构分析，不依赖运行时或 AST 之外的外部服务；SonarQube 偏企业级全面质量管理；ESLint 偏代码风格；CodeQL 偏安全漏洞检测。Fallow 在 TypeScript/JavaScript 领域的性能和零配置优势明显。

§8 一句话结论

Fallow 是 TypeScript/JavaScript 代码库质量分析的瑞士军刀——零配置、Rust 级速度、MCP 集成让它成为 AI Coding 时代代码审查和债务追踪的高性价比选择；使用时应与 ESLint 配合，并将 audit 命令作为 PR Gate 的一部分持续运行。