# @doist/react-compiler-tracker 中文文档

规范地址：https://npmcn.com/package/%40doist/react-compiler-tracker/

版本：3\.0\.4
npm 元数据更新时间：2026-11-04T08:51:07.553Z
中文译文更新时间：2026-11-12T14:56:13.319Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40doist/react-compiler-tracker
原文对照：https://npmcn.com/package/%40doist/react-compiler-tracker/?lang=original
项目主页：https://github.com/Doist/react-compiler-tracker#readme
源码仓库：https://github.com/Doist/react-compiler-tracker

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：79.3 kB，17 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.0\.0
- 运行依赖：2 个
- peer 依赖：@babel/core ^7\.26\.0，@babel/preset-react ^7\.0\.0，@babel/preset-typescript ^7\.0\.0，babel-plugin-react-compiler ^1\.0\.0
- 首次发布：2026-01-17T00:37:42.619Z
- 最新版本发布：2026-11-04T08:51:07.190Z
- 近 30 天下载量：10053（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：19（近 12 个月 19 个）

## 中文简介

反应编译器违规跟踪器, 帮助迁移和防止回归

## 安装

```sh
npm install @doist/react-compiler-tracker
```

也可以使用：`pnpm add @doist/react-compiler-tracker`、`yarn add @doist/react-compiler-tracker`、`bun add @doist/react-compiler-tracker`

## README

# 反应编译器跟踪器

[![npm version](https://img.shields.io/npm/v/@doist/react-compiler-tracker)](https://www.npmjs.com/package/@doist/react-compiler-tracker) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Node.js](https://img.shields.io/node/v/@doist/react-compiler-tracker)](https://nodejs.org/)

这个 [React 编译器](https://react.dev/learn/react-compiler) 自动记住您的组件, 从而不再需要 `useCallback` 财务报告和审定财务报表 `useMemo`然而,某些代码模式导致编译器退出. 发生这种情况时,你的组件会失去自动优化,可能造成性能回落.

灵感来自 [插图](https://github.com/hjylewis/esplint) 财务报告和审定财务报表 [反应-编译-标记](https://github.com/blazejkustra/react-compiler-marker),此工具跟踪编译器在 a 中的错误 `.react-compiler.rec.json` 与 Git 钩和 CI 合并,防止出现新的违规情况.

## 先决条件

此工具将您与 Babel 和 React 编译器的源文件编译, 使用您工程中安装的文件, 以便它所报的违反内容与您自己的构建生成的文件相匹配 。 还没有安装的话安装它们:

```bash
npm install --save-dev babel-plugin-react-compiler @babel/core@^7.26.0 @babel/preset-react@^7 @babel/preset-typescript@^7
```

Babel 8 尚未支持,因为 `babel-plugin-react-compiler` 运行时报告违反有效代码.

## 安装

```bash
npm install --save-dev @doist/react-compiler-tracker
```

## 配置

创建一个 `.react-compiler-tracker.config.json` 用于自定义工具行为的文件 :

```json
{
    "recordsFile": ".react-compiler.rec.json",
    "sourceGlob": "src/**/*.{js,jsx,ts,tsx}"
}
```

所有字段都是可选的. 默认值见上文.

| 选项 | 说明 | 默认 |
| --- | --- | --- |
| `recordsFile` | 记录文件的路径 | `.react-compiler.rec.json` |
| `sourceGlob` | 源文件的 Glob 模式 | `src/**/*.{js,jsx,ts,tsx}` |

### 单项使用

在单列波中,从您的软件包目录中运行工具。 配置文件及所有路径相对于您运行命令的位置 。 默认在框中通常有效 :

```
my-monorepo/
├── packages/
│   └── frontend/
│       ├── .react-compiler-tracker.config.json  # Optional config
│       ├── .react-compiler.rec.json             # Records file
│       └── src/
│           └── ...
```

如果您的源文件位于不同的位置( 例如 ) , `app/` 改为 `src/`,自定义配置 :

```json
{
    "sourceGlob": "app/**/*.{ts,tsx}"
}
```

## 使用量

### `--overwrite`

通过扫描所有匹配的源文件来重新生成整个记录文件 `sourceGlob`。用于初始化或从跳过的 Git 钩子取出更改.

```bash
npm exec --no -- @doist/react-compiler-tracker --overwrite
```

### `--stage-record-file <file1> <file2> ...`

检查所提供的文件并更新记录。 如果错误增加(防止执行),则以代码1退出,否则将更新已检查文件的记录文件。 报告错误减少时,庆祝你的进展。 删除的文件会自动从记录中删除(不需要通过路径).

```bash
npm exec --no -- @doist/react-compiler-tracker --stage-record-file src/components/Button.tsx src/hooks/useData.ts
```

如果没有提供文件,则以成功消息清洁退出.

### `--check-files <file1> <file2> ...`

在不更新记录的情况下检查特定文件 。 如果选中的文件显示增加错误计数( 或新出错) , 或不存在任何提供的文件, 则退出代码 1 。 当错误减少时报告, 庆祝你的进展。 主要是CI确保PR不会引入新的编译器错误.

```bash
npm exec --no -- @doist/react-compiler-tracker --check-files src/components/Button.tsx src/hooks/useData.ts
```

### 没有旗帜

检查匹配的所有源文件 `sourceGlob` 并报告总出错数。 记录文件是 **没有** 在此模式中更新.

```bash
npm exec --no -- @doist/react-compiler-tracker
```

### `--show-errors`

显示来自编译器的错误信息,包括文件路径、行号以及出错原因。 可以与任何命令结合. 对所有已检查的文件显示错误, 不论是否增加 .

```bash
npm exec --no -- @doist/react-compiler-tracker --check-files --show-errors src/components/Button.tsx
```

错误增加时的示例输出 :

```
Errors:
    - src/components/Button.tsx: Line 15: Cannot access refs during render (x2)
    - src/components/Button.tsx: Line 28: Invalid hook usage
❌ React Compiler errors have increased in:
  • src/components/Button.tsx: +3

Please fix the errors and run the command again.
```

当没有引入新错误时, 您仍然可以看到现有的错误 :

```
Errors:
    - src/components/Button.tsx: Line 15: Cannot access refs during render (x2)
✅ No new React Compiler errors in checked files
```

## 整合实例

### 阶段

单位 `package.json`数字 :

```json
{
    "lint-staged": {
        "*.{js,jsx,ts,tsx}": "npm exec --no -- @doist/react-compiler-tracker --stage-record-file"
    }
}
```

相匹配的文件会自动作为参数传递到命令中.

### GitHub 动作 CI

```yaml
- name: Check React Compiler violations
  run: |
      # Get changed files in the PR
      FILES=$(git diff --name-only origin/main...HEAD -- '*.tsx' '*.ts' '*.jsx' '*.js' | tr '\n' ' ')
      if [ -n "$FILES" ]; then
        npm exec --no -- @doist/react-compiler-tracker --check-files $FILES
      fi
```

### 承诺前钩 (手工)

```bash
#!/bin/sh
# Get staged files and pass them to the tracker
# (deleted files are auto-detected from records, no need to pass them)
FILES=$(git diff --diff-filter=ACMR --cached --name-only -- '*.tsx' '*.ts' '*.jsx' '*.js' | tr '\n' ' ')
if [ -n "$FILES" ]; then
  npm exec --no -- @doist/react-compiler-tracker --stage-record-file $FILES
fi
```

## 释放

这个项目使用 [请放行](https://github.com/googleapis/release-please) 自动释放。 提交合并为 `main` 与 `fix:` 触发补丁释放, `feat:` 引发轻微释放 `feat!:` 或者说 `fix!:` 触发主要释放.

当在 `main`,释放 - 请创建释放 PR。 将它合并到 npm 和 GitHub 套件 .

## 许可证

释放 [MIT 许可证](https://opensource.org/licenses/MIT)。 。 。 .

## 常见问题

### @doist/react-compiler-tracker 是什么？

反应编译器违规跟踪器, 帮助迁移和防止回归

### 如何安装 @doist/react-compiler-tracker？

在项目目录运行 npm install @doist/react-compiler-tracker，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@babel/core（^7\.26\.0）、@babel/preset-react（^7\.0\.0）、@babel/preset-typescript（^7\.0\.0）、babel-plugin-react-compiler（^1\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 react-compiler-tracker，可以用 npx react-compiler-tracker 直接运行。

### @doist/react-compiler-tracker 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/doist\_\_react-compiler-tracker 是否存在。

### @doist/react-compiler-tracker 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @doist/react-compiler-tracker 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @doist/react-compiler-tracker 可以商用吗？

@doist/react-compiler-tracker 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @doist/react-compiler-tracker 的下载量有多少？

根据 npm 官方下载统计，@doist/react-compiler-tracker 在 2026/10/13 – 2026/11/11 这 30 天内被下载 10,053 次，日均约 335 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @doist/react-compiler-tracker 还在维护吗？

最新版本 3\.0\.4 发布于 2026/11/04（9 天前）；至今共发布 19 个版本，其中过去 12 个月发布了 19 个；首次发布于 2026/01/17。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。