react-scanner 常见问题与避坑指南：从安装到报告的 12 个高频问题解答

【免费下载链接】react-scanner Extract React components and props usage from code. 项目地址: https://gitcode.com/gh_mirrors/re/react-scanner

react-scanner 是一款静态分析工具，能够扫描项目代码并提取 React 组件与 props 的使用情况，最终输出结构化的 JSON 报告。无论你想统计设计系统组件被引用了多少次、分析某个 prop 的取值分布，还是排查不用的组件，它都能帮你快速拿到答案。本文汇总了从安装、配置到生成报告的 12 个高频问题，帮你避开最常见的坑，顺利跑通第一次扫描任务。

1. 安装 react-scanner 失败，错误信息看不懂怎么办？🤔

安装命令其实很简单：npm install --save-dev react-scanner。如果你在这步卡住，先检查两点：

• Node 版本：项目要求 Node.js 14 及以上，版本过低会直接安装失败。
• 安装位置：它只用于开发期分析，务必作为开发依赖（--save-dev）安装。

网络不稳定导致的安装失败也常见，换用国内 npm 镜像源后重试通常就能解决。

2. 运行后提示 "No files found to scan"，为什么扫描不到任何文件？

这个报错说明在 crawlFrom 目录下没有找到任何匹配 globs 的文件。最常见的三个原因：

• crawlFrom 路径写错，指向了空目录或不存在的位置。
• 默认 globs 是 **/!(*.test|*.spec).@(js|ts)?(x)，它会主动跳过 *.test.js、*.spec.tsx 这类测试文件，如果项目里只有测试文件就会报这个错。
• 自定义 globs 语法写错，导致匹配不到文件。

想只扫描特定后缀（比如 .jsx），覆盖 globs 配置即可，参见示例 noFilesFound.config.js。

3. 报错 "crawlFrom path doesn't exist"，路径到底怎么填？

这个错误来自配置校验阶段，说明 crawlFrom 指向的目录不存在。注意三点：

• crawlFrom 是必填项，省略会直接报 "crawlFrom is missing"。
• 相对路径的基准是配置文件所在的目录，而不是你执行命令的终端目录——这是新手最容易踩的坑。
• 拿不准时直接写绝对路径最稳妥。

校验逻辑可在 src/utils.js 中看到，非常清晰。

4. exclude 配置怎么写才不报错？

exclude 支持两种合法形式，写错会触发严格校验：

• 数组形式：每一项必须是字符串或正则，例如 exclude: ["node_modules", /^\./]，用来精确排除目录名。
• 函数形式：接收一个目录名参数，返回 true 表示该目录应被跳过，适合复杂场景。

最常见的错误是把 exclude: "tests" 写成了字符串，此时会直接报 "exclude should be an array or a function"。

5. globs 配置有误，扫描结果总是缺东少西？

globs 同样有严格的格式要求：

• 必须是数组，且数组元素必须是字符串。
• 支持 picomatch 的 glob 语法，如 ["**/*.jsx", "!**/__tests__/**"]，用 ! 开头的规则表示排除。
• 写错 glob 的常见后果就是匹配不到文件，最终又回到 "No files found to scan"。

6. 报告里只有顶层组件，Footer.Content 这样的子组件去哪了？

这是 includeSubComponents 配置的问题，它默认是 false，此时 Footer.Content、Footer.Content.Legal 这类嵌套子组件会被过滤掉。

• 设置为 true 后，所有层级的子组件都会出现在报告中。
• 在原始 JSON 报告中，子组件以嵌套的 components 字段组织，例如 Footer.components.Content。

7. importedFrom 过滤不生效，无关组件全进来了？

importedFrom 用来限制只报告从指定模块导入的组件，例如只想统计来自设计系统库 basis 的组件：

importedFrom: "basis"

它支持字符串或正则两种写法（如 /react|basis/），匹配的是 import 语句的来源模块名。如果你没配置它，扫描器会报告所有组件，结果自然"又全又杂"，示例见 multipleProcessors.config.js。

8. 报错 unknown processor，内置处理器到底有哪些？

报错信息中会列出所有已知处理器名称。react-scanner 内置三个处理器：

处理器	输出内容
count-components	每个组件被使用的次数，如 { "Text": 10 }
count-components-and-props	组件次数 + 各 props 的使用次数（默认处理器）
raw-report	最原始的扫描 JSON 报告，包含 importInfo、props、propsSpread、location 等字段

按名称字符串直接使用即可，如 processors: ["count-components"]。

9. processors 数组写错，运行直接报配置错误？

processors 支持三种合法形式，校验非常严格：

• 字符串形式："count-components"，必须是已知的内置处理器。
• 元组形式：["count-components", { outputTo: "report.json" }]，数组必须恰好两个元素，且第二项必须是对象。
• 函数形式：自定义处理器，可拿到 report、prevResults、output 等参数，支持异步。

元组缺选项对象、数量不对都会报错，所有校验规则都在 src/utils.js 中，遇到报错对照检查即可。

10. 想把报告保存成文件，而不是打印到控制台？

所有内置处理器都支持 outputTo 选项，例如：

processors: [
  ["count-components-and-props", { outputTo: "reports/result.json" }]
]

• outputTo 的相对路径以 rootDir 为基准解析，输出时会自动创建缺失的目录。
• 省略 outputTo 时，结果默认打印到控制台。
• 通过程序化 API 调用时，默认通过返回值获取结果而非打印。

11. 扫描 .ts/.tsx 文件报 "Failed to parse" 怎么办？

react-scanner 使用 typescript-estree 解析代码，本身就支持 TypeScript，无需额外配置。出现 "Failed to parse" 说明某个文件解析失败，此时该文件会被跳过，不影响整体扫描。

• 错误信息中会打印具体文件路径，方便定位。
• 常见诱因是 JSX 标签未闭合、字符串引号不匹配等语法错误，修复后重新扫描即可。
• 该容错逻辑在 src/scan.js 中，即使个别文件出错也不会中断整个任务。

12. 如何在 Node 代码里以编程方式调用 react-scanner？

除了 CLI 方式（npx react-scanner -c 配置文件路径），你也可以在代码中直接调用：

import scanner from "react-scanner";
const output = await scanner.run(config);

• 配置直接以对象形式传入，不再需要单独的配置文件。
• 返回值是最后一个处理器的结果，方便继续加工或写入自己的存储系统。
• 想深入理解运行流程，可以直接阅读 src/scanner.js 和 src/run.js，核心逻辑并不复杂。

总结

react-scanner 的配置项不算多，但每个都有严格的类型校验，绝大多数报错都来自配置格式问题。把 crawlFrom、globs、processors 这三处写对，再用 importedFrom 和 includeSubComponents 做精细控制，基本就能顺利产出组件使用报告。希望这 12 个问题的解答能帮你少走弯路，快速拿到第一份组件使用统计报告。

【免费下载链接】react-scanner Extract React components and props usage from code. 项目地址: https://gitcode.com/gh_mirrors/re/react-scanner