# 策展 · X (Twitter) 🔥🔥

> 作者：Aiden Bai (@aidenybai) · 平台：X (Twitter) · 日期：2026-05-10

> 原始來源：https://x.com/aidenybai/status/2052780632510775469

## 中文摘要

React Doctor v2 推出診斷 Agent React 程式碼。

Aiden Bai 發布 React Doctor v2，這款工具透過單一指令掃描 React 程式庫，輸出 0 到 100 的健康分數，並提供狀態管理、效能、架構、安全性、無障礙與死程式碼等類別的具體診斷，針對 Agent 常寫出的壞程式碼特別設計。相容 Next.js、Vite 與 React Native，使用者可在數分鐘內修復應用程式問題。

**快速安裝與執行**

在專案根目錄執行以下指令，即可立即試用：

```bash
npx -y react-doctor@latest .
```

工具會自動偵測框架與 React 版本，調整規則並切換診斷項目。分數標準為：75+ 優秀、50 到 74 需要改善、低於 50 嚴重問題。掃描結果包含前三項主要規則，若需完整細節，可加 `--verbose` 旗標。

**適用於程式撰寫 Agent**

為避免 Agent 一開始就產生壞程式碼，可安裝專屬設定，讓 Agent 學習 React 最佳實務：

```bash
npx -y react-doctor@latest install
```

工具會提示選擇偵測到的 Agent（如 Claude Code、Cursor、Codex、OpenCode 等 50+ 種），使用 `--yes` 旗標可略過提示，直接安裝所有。

**GitHub Actions 整合**

在 CI/CD 中使用以下 YAML 配置，掃描變更檔案並輸出分數：

```yaml
- uses: actions/checkout@v5
  with:
    fetch-depth: 0 # required for --diff
- uses: millionco/react-doctor@main
  with:
    diff: main
    github-token: ${{ secrets.GITHUB_TOKEN }}
```

設定 `github-token` 後，在 pull request 事件中會自動發佈診斷為 PR 評論。動作也輸出 `score`（0 到 100），可用於後續步驟。

**配置檔案設定**

在專案根目錄建立 `react-doctor.config.json`，自訂忽略規則：

```json
{
  "ignore": {
    "rules": ["react/no-danger", "jsx-a11y/no-autofocus"],
    "files": ["src/generated/**"],
    "overrides": [
      {
        "files": ["components/diff/**"],
        "rules": ["react-doctor/no-array-index-as-key"]
      }
    ]
  }
}
```

- `ignore.rules`：全域停用特定規則。
- `ignore.files`：匹配檔案停用所有規則。
- `ignore.overrides`：特定目錄停用特定規則。
也可於 `package.json` 使用 `"reactDoctor"` 鍵。CLI 旗標優先於配置。

工具尊重 `.gitignore`、`.eslintignore`、`.oxlintignore`、`.prettierignore` 與 `.gitattributes` 中的 `linguist-vendored` / `linguist-generated` 註解。內嵌 `// eslint-disable*` 與 `// oxlint-disable*` 註解同樣有效。若有 `.oxlintrc.json` 或 `.eslintrc.json`，其規則會自動合併計入分數，設 `adoptExistingLintConfig: false` 可停用。

**內嵌抑制註解**

單行抑制：

```tsx
// react-doctor-disable-next-line react-doctor/no-cascading-set-state
useEffect(() => {
  setA(value);
  setB(value);
}, [value]);
```

同一行多規則用逗號分隔。JSX 內使用區塊註解：

```tsx
{/* react-doctor-disable-next-line react/no-danger */}
<div dangerouslySetInnerHTML={{ __html }} />
```

多行 JSX 將註解置於開頭標籤上方，即涵蓋整個屬性清單。

**獨立 Lint plugin**

規則集提供 oxlint 與 ESLint plugin，可整合既有 lint 引擎。

**oxlint 配置**（`.oxlintrc.json`）：

```jsonc
{
  "jsPlugins": [{ "name": "react-doctor", "specifier": "react-doctor/oxlint-plugin" }],
  "rules": {
    "react-doctor/no-fetch-in-effect": "warn",
    "react-doctor/no-derived-state-effect": "warn",
  },
}
```

**ESLint 平坦配置**：

```js
import reactDoctor from "react-doctor/eslint-plugin";

export default [
  reactDoctor.configs.recommended,
  reactDoctor.configs.next,
  reactDoctor.configs["react-native"],
  reactDoctor.configs["tanstack-start"],
  reactDoctor.configs["tanstack-query"],
];
```

完整規則清單見 [`oxlint-config.ts`](https://github.com/millionco/react-doctor/blob/main/packages/react-doctor/src/oxlint-config.ts)。

**CLI 完整參考**

```
Usage: react-doctor [directory] [options]

Options:
  -v, --version           display the version number
  --no-lint               skip linting
  --no-dead-code          skip dead code detection
  --verbose               show every rule and per-file details (default shows top 3 rules)
  --score                 output only the score
  --json                  output a single structured JSON report
  -y, --yes               skip prompts, scan all workspace projects
  --full                  skip prompts, always run a full scan
  --project <name>        select workspace project (comma-separated for multiple)
  --diff [base]           scan only files changed vs base branch
  --staged                scan only staged files (for pre-commit hooks)
  --offline               skip telemetry
  --fail-on <level>       exit with error on diagnostics: error, warning, none
  --annotations           output diagnostics as GitHub Actions annotations
  --explain <file:line>   diagnose why a rule fired or why a suppression didn't apply
  -h, --help              display help
```

- `--explain <file:line>`：診斷規則觸發或抑制失效原因，`--verbose` 與 `--json` 也提供 `diagnostic.suppressionHint`。
- `--json`：輸出單一結構化 JSON 報表，錯誤時 `ok: false`，stdout 永遠有效 JSON。

**配置鍵值表**

| Key                        | Type                             | Default  |
| -------------------------- | -------------------------------- | -------- |
| `ignore.rules`             | `string[]`                       | `[]`     |
| `ignore.files`             | `string[]`                       | `[]`     |
| `ignore.overrides`         | `{ files, rules? }[]`            | `[]`     |
| `lint`                     | `boolean`                        | `true`   |
| `deadCode`                 | `boolean`                        | `true`   |
| `verbose`                  | `boolean`                        | `false`  |
| `diff`                     | `boolean \| string`              |          |
| `failOn`                   | `"error" \| "warning" \| "none"` | `"none"` |
| `customRulesOnly`          | `boolean`                        | `false`  |
| `share`                    | `boolean`                        | `true`   |
| `textComponents`           | `string[]`                       | `[]`     |
| `rawTextWrapperComponents` | `string[]`                       | `[]`     |
| `respectInlineDisables`    | `boolean`                        | `true`   |
| `adoptExistingLintConfig`  | `boolean`                        | `true`   |

`textComponents` 用於 `rn-no-raw-text` 規則，列出如自訂 `Typography` 等類似 React Native `<Text>` 的元件。`rawTextWrapperComponents` 則限於純字串子元件的包裝器（如 `heroui-native` 的 `Button`），混合子元件仍會警示。

**Node.js API**

程式化使用：

```js
import { diagnose, toJsonReport, summarizeDiagnostics } from "react-doctor/api";

const result = await diagnose("./path/to/your/react-project");

console.log(result.score); // { score: 82, label: "Great" } or null
console.log(result.diagnostics); // Diagnostic[]
console.log(result.project); // detected framework, React version, etc.
```

`diagnose` 接受第二參數 `{ lint?: boolean, deadCode?: boolean }`。另有 `toJsonReport`、`summarizeDiagnostics` 等輔助函式，完整類型見 [`packages/react-doctor/src/api.ts`](https://github.com/millionco/react-doctor/blob/main/packages/react-doctor/src/api.ts)。

**排行榜表現**

React Doctor 掃描頂尖 React 程式庫，分數排名自動更新自 [millionco/react-doctor-benchmarks](https://github.com/millionco/react-doctor-benchmarks)：

| #  | Repo | Score |
| -- | ---- | ----: |
| 1  | [executor](https://github.com/RhysSullivan/executor) | 96 |
| 2  | [nodejs.org](https://github.com/nodejs/nodejs.org) | 86 |
| 3  | [tldraw](https://github.com/tldraw/tldraw) | 70 |
| 4  | [t3code](https://github.com/pingdotgg/t3code) | 68 |
| 5  | [better-auth](https://github.com/better-auth/better-auth) | 64 |
| 6  | [excalidraw](https://github.com/excalidraw/excalidraw) | 63 |
| 7  | [mastra](https://github.com/mastra-ai/mastra) | 63 |
| 8  | [payload](https://github.com/payloadcms/payload) | 60 |
| 9  | [typebot](https://github.com/baptisteArno/typebot.io) | 57 |
| 10 | [plane](https://github.com/makeplane/plane) | 56 |

完整排行見 [排行榜頁面](https://react.doctor/leaderboard)。使用者可回覆專案分數，比較排名：[https://react.doctor/leaderboard](https://react.doctor/leaderboard)。

**貢獻與資源**

試用示範：[https://react.doctor](https://react.doctor)。貢獻回饋步驟：

1. `git clone https://github.com/millionco/react-doctor`
2. `cd react-doctor`
3. `pnpm install`
4. `pnpm build`
5. `node packages/react-doctor/bin/react-doctor.js /path/to/your/react-project`

回報 bug 至 [issue tracker](https://github.com/millionco/react-doctor/issues)。專案為 MIT 授權開源軟體，GitHub 儲存庫：[https://github.com/millionco/react-doctor](https://github.com/millionco/react-doctor)。npm 套件顯示版本與下載量，最新版支援黑暗/明亮模式 logo。

## 標籤

Agent, 新產品, 開源專案, React, Next, React Doctor