企业官网建设流程全解析

react-scanner 配置文件完全指南：从零掌握全部配置项，精准控制组件扫描

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

react-scanner 是一个通过静态分析代码（支持 TypeScript）来提取 React 组件及 props 使用情况的扫描工具，而它的全部行为都由一份react-scanner 配置文件控制。无论你是刚接触组件使用统计的新手，还是想深入定制扫描规则的开发者，这份 react-scanner 配置项完全指南都能帮你从零起步，精准控制组件扫描的范围、深度与输出结果。只需一次配置，就能知道你的设计系统组件被使用了多少次、哪些 props 最受欢迎。

react-scanner 是什么：读懂组件使用情况的利器

在开始配置之前，先花 30 秒了解这个工具能做什么。react-scanner 会先遍历指定目录、编译出待扫描文件清单，然后逐个文件解析 JSX，最终把渲染过的组件和它们的 props 汇总成一份 JSON 报告。

简单说，它能回答三个关键问题：

• 某个组件在项目里被用了几次？
• 某个组件上哪些 props 用得最多？
• 某个 prop 的值分布如何，是否该考虑废弃？

拿到答案后，你既可以把结果打印到控制台，也可以写入文件归档。整个流程全部由配置文件驱动，下面我们就一步步掌握每个配置项。

快速开始：react-scanner 配置文件安装与基础用法

安装只需一条命令：

npm install --save-dev react-scanner

安装完成后，创建一个配置文件（放在项目任意位置均可），例如react-scanner.config.js，然后运行：

npx react-scanner -c /path/to/react-scanner.config.js

一个最基础的 react-scanner 配置文件长这样：

module.exports = { crawlFrom: "./src", includeSubComponents: true, importedFrom: "basis", };

运行后，控制台会输出类似这样的统计结果——每个组件用了多少次、每个 prop 用了多少次：

{ "Text": { "instances": 17, "props": { "margin": 6, "color": 4, "textStyle": 1 } }, "Button": { "instances": 10, "props": { "width": 10, "variant": 5, "type": 3 } } }

如果你不想走命令行，也可以编程方式调用：把配置对象直接传给scanner.run(config)即可（相关入口见 src/scanner.js 和 src/index.js）。

最核心的 3 个 react-scanner 配置项

配置项不少，但真正决定“扫哪里、怎么筛、报什么”的核心只有下面 3 个。

1. crawlFrom：设置扫描起点目录

crawlFrom是唯一必填项，它指定爬取文件的起始目录，支持绝对路径，也支持相对于配置文件所在位置的相对路径。路径不存在时，工具会直接报错提示。

module.exports = { crawlFrom: "./src", // 扫描 src 目录下所有匹配文件 };

2. includeSubComponents：是否统计子组件

React 组件经常用点语法组织，比如Footer.Content.Legal。把这个配置项设为true，子组件也会被逐一统计；设为false（默认值）则只统计Footer本身。

module.exports = { crawlFrom: "./src", includeSubComponents: true, // Footer.Content.Legal 也会被报告 };

3. importedFrom：只统计指定来源的组件

这是最实用的“过滤神器”。当你的项目里既有第三方组件、又有自家设计系统组件时，用importedFrom限定模块来源，就能只关注你想分析的那部分。它支持字符串精确匹配，也支持正则模糊匹配：

module.exports = { crawlFrom: "./src", importedFrom: /react|basis/, // 只统计从 react 或 basis 导入的组件 };

进阶筛选配置：精准控制扫描范围

当项目规模变大，你可能需要更精细的“裁切”能力，下面 3 个配置项就是为此准备的。

exclude：排除不想扫描的目录

exclude接受一个数组或一个函数。数组里每一项可以是字符串或正则：目录名精确等于字符串、或匹配正则时，该目录会被跳过。函数形式则更灵活，接收目录名并返回是否排除。

module.exports = { crawlFrom: "./src", exclude: ["node_modules", /__tests__/], };

globs：自定义文件匹配规则

默认情况下，react-scanner 只扫描**/!(*.test|*.spec).@(js|ts)?(x)这类文件，也就是自动跳过*.test.js之类的测试文件。你可以用globs覆盖默认规则，比如只扫 JSX 文件：

module.exports = { crawlFrom: "./src", globs: ["**/*.jsx"], };

components：只报告关心的组件

如果你只想知道少数几个组件的使用情况，用components对象把组件名列为true即可，未列出的组件一律不报告：

module.exports = { crawlFrom: "./src", components: { Button: true, Text: true, }, };

自定义扫描行为：rootDir 与两个钩子函数

rootDir：统一相对路径的基准点

rootDir指向项目根目录，所有相对路径都以它为基准。使用配置文件时，它默认就是配置文件所在目录，一般无需手动设置。

getComponentName：自定义组件命名规则

报告中的组件名默认取自 import 声明（imported || local）。如果你的导入写法比较特殊，可以通过getComponentName函数定制命名规则，例如默认导入时取本地名。

getPropValue：还原真实的 prop 表达式

这是一个高阶玩法。默认情况下，表达式或变量作为 prop 值时，报告里只显示 AST 类型（比如(Identifier)）。如果你希望看到真实传入的表达式，可以配合escodegen等工具，在getPropValue里针对指定组件和 prop 还原源码（相关扫描逻辑见 src/scan.js）。

processors 配置：让扫描结果真正有用

扫描产生的原始 JSON 报告要经过processors（处理器）加工才有实际价值。processors 是数组，默认值是["count-components-and-props"]，几种写法都要掌握。

内置处理器：三种常用统计方式

用字符串形式直接启用内置处理器：

module.exports = { crawlFrom: "./src", processors: ["count-components"], // 只统计组件出现次数 };

内置处理器共有 3 个，实现代码都在 src/processors/ 目录下：

传递选项：用元组形式配置输出路径

想把结果保存成文件？用[名称, 选项]的元组形式，通过outputTo指定输出路径（相对根目录）：

module.exports = { crawlFrom: "./src", processors: [["count-components", { outputTo: "./report.json" }]], };

自定义处理器：串联前序结果

处理器也可以是函数，甚至支持异步。函数会收到一个包含report、prevResult、output等字段的对象，方便你取用前一个处理器的结果继续加工，比如把统计结果 POST 到自己的存储服务。

常见配置错误自查清单

配置文件写错了会很困惑，好在 react-scanner 会在启动时做配置校验（校验逻辑见 src/utils.js）。最常见的 5 个坑帮你提前避雷：

• ❌crawlFrom缺失或不是字符串——这是必填项
• ❌exclude、globs不是数组，或数组元素类型不对
• ❌components对象里的值不是true
• ❌includeSubComponents不是布尔值
• ❌ 处理器名称拼写错误，或元组形式第二项不是对象

总结：一份完整的 react-scanner 配置示例

最后送上一份综合示例，把常用配置项一次配齐，作为你项目里的起步模板：

module.exports = { crawlFrom: "./src", exclude: [/__tests__/], globs: ["**/*.{js,jsx,ts,tsx}"], includeSubComponents: true, importedFrom: /^@my-company\//, processors: [ "count-components", ["count-components-and-props", { outputTo: "./reports/usage.json" }], ], };

掌握这份 react-scanner 配置文件完全指南后，从扫描范围、组件筛选到结果输出，你都能精准控制。快去试试看，让组件使用数据为你的重构、文档和设计系统迭代提供依据吧！

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