Create React App 编辑器集成实战：语法高亮、ESLint 规则扩展、断点调试与 Prettier 自动格式化

本文基于 Create React App 官方文档 "Setting Up Your Editor"，系统讲解如何让编辑器与 CRA 工具链深度配合：从语法高亮的正确配置，到利用 package.json 中的 eslintConfig 扩展默认 ESLint 规则集，再到 VS Code / WebStorm 的断点调试配置，以及用 husky + lint-staged + Prettier 实现提交前自动格式化。读完本文，你可以完整理解 CRA 中 ESLint 配置的分层结构（base 与 react-app 两套配置各自的作用），并能直接复制文中的配置片段在自己项目中落地。

配置语法高亮

Create React App 使用 Babel 处理现代 JavaScript 语法，因此编辑器要正确高亮 JSX、类属性等新语法，需要按 Babel 官方编辑器文档进行配置（该文档覆盖了主流编辑器）。这一步的关键是让编辑器使用 Babel 的解析能力（如 VS Code 的 Esbuild/Babel 插件、WebStorm 原生支持），否则类属性、可选链等写法可能出现高亮缺失或误报。

在编辑器中显示 Lint 输出

版本与依赖前提：

• 该功能在 react-scripts@0.2.0 及以上版本可用；
• 使用 react-scripts@2.0.3 及以上版本新建的项目开箱即用；
• 仅支持 npm 3 及以上。

Sublime Text、Atom、Visual Studio Code 等编辑器都提供 ESLint 插件。Lint 本身并不依赖这些插件——即使在编辑器里不做任何配置，终端和浏览器控制台中也都能看到 linter 输出。如果你希望 lint 结果直接显示在编辑器里，需要安装对应编辑器的 ESLint 插件/扩展。

一个重要的边界：即使你自定义了 ESLint 配置，这些改动只影响编辑器集成，不会影响终端和浏览器内的 lint 输出。原因在于 CRA 构建时的 lint 是 Webpack 构建管线的一部分，而不是读取你的编辑器配置。从源码结构看，webpack.config.js 中通过 ESLintPlugin 执行 lint：

• 检查范围是 src 目录（context: paths.appSrc），扩展名为 js, mjs, jsx, ts, tsx；
• baseConfig 强制继承 eslint-config-react-app/base，即 CRA 有意提供的一套最小规则集，用于发现常见错误；用户配置是在这个基础之上叠加的；
• failOnError 的逻辑为 !(isEnvDevelopment && emitErrorsAsWarnings)，其中 emitErrorsAsWarnings 由环境变量 ESLINT_NO_DEV_ERRORS === 'true' 控制（见 webpack.config.js）；也就是说开发模式下 error 默认会让构建失败，而可用 ESLINT_NO_DEV_ERRORS 将其降级为警告；此外还可通过 DISABLE_ESLINT_PLUGIN === 'true' 整体关闭该插件；
• 启用 cache，缓存位置在 node_modules/.cache/.eslintcache。

正因为构建管线使用自己的 baseConfig 叠加策略，编辑器端对规则的增删（尤其是纯风格类规则）不会改变构建时的 lint 行为。如果你想强制统一的代码风格，官方建议用 Prettier 而不是 ESLint 风格规则（下文会给出完整落地方案）。

扩展或替换默认 ESLint 配置

你可以在项目根目录 package.json 的 eslintConfig 字段中扩展（extend）默认的 react-app 基础配置，也可以完全替换它。有几点需要注意：

1. 官方强烈推荐扩展基础配置而不是删除它，因为移除它可能引入难以排查的问题；
2. 使用 TypeScript 时，需要为那些只应作用于 TypeScript 文件的规则提供 overrides 对象；
3. 设为 "error" 的规则会导致项目构建失败（对应上文 ESLintPlugin 的 failOnError 行为），请务必谨慎。

CRA 新建项目时，init.js 会自动写入默认配置：

{
  "eslintConfig": {
    "extends": "react-app"
  }
}

执行 npm run eject 时，eject.js 也只在 appPackage.eslintConfig 不存在时才补写该配置——如果你已经自定义过，eject 会保留你的配置，这正是上面"自定义只叠加不覆盖"机制在工具链层面的体现。

默认配置的具体内容由 eslint-config-react-app/index.js 定义。从源码结构看，该配置：

• 继承 base.js（root: true、@babel/eslint-parser、react 插件、browser/commonjs/es6/jest/node 五类环境，以及 react/jsx-uses-vars、react/jsx-uses-react 两条最小规则）；
• 加载 import、flowtype、jsx-a11y、react-hooks 四个插件，并配置了大量 warn 级规则，例如 array-callback-return、eqeqeq（smart 模式）、react-hooks/exhaustive-deps、jsx-a11y/alt-text 等；
• 其中少数规则是 error 级，会直接阻断构建，例如 no-undef、react-hooks/rules-of-hooks、import/first、react/no-typos、react/jsx-no-undef；
• no-restricted-globals 通过 confusing-browser-globals 黑名单，把 name、status 等容易被误用的浏览器全局变量标为 error，要求显式写 window.name 等；
• 内置了 files: ['**/*.ts?(x)'] 的 overrides，为 TypeScript 文件切换到 @typescript-eslint/parser，并按 typescript-eslint 的对应关系成对关闭/启用规则（如关闭 no-undef 启用 @typescript-eslint/no-redeclare）。这也解释了为什么官方文档强调：给 TS 文件加专属规则时必须走 overrides，而不是直接写在全局 rules 里。

以下示例同时演示了"扩展共享配置 + 全局新规则 + TS 专属规则"三种写法：

{
  "eslintConfig": {
    "extends": ["react-app", "shared-config"],
    "rules": {
      "additional-rule": "warn"
    },
    "overrides": [
      {
        "files": ["**/*.ts?(x)"],
        "rules": {
          "additional-typescript-only-rule": "warn"
        }
      }
    ]
  }
}

要点回顾：extends 数组中 "react-app" 保留在前、共享配置追加在后；全局 rules 作用于所有 JS/TS 文件；overrides 中的 "files": ["**/*.ts?(x)"] 与默认配置里的 TS 文件匹配模式一致，确保 TS 专属规则不会误伤 JS 文件；两条新规则都用了 "warn"，如果想让它们阻断构建可改成 "error"，但需知悉这会终止 build。

在编辑器中调试

该功能目前仅支持 Visual Studio Code 和 WebStorm。

VS Code 和 WebStorm 都能开箱即用地调试 Create React App 项目。你可以不离开编辑器就编写并调试 React 代码，实现连续的开发现场，减少工具切换带来的上下文损耗。

Visual Studio Code

要求安装最新版 VS Code。然后在项目根目录的 .vscode 文件夹中创建（或编辑）launch.json，加入以下配置块：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Chrome",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:3000",
      "webRoot": "${workspaceFolder}/src",
      "sourceMapPathOverrides": {
        "webpack:///src/*": "${webRoot}/*"
      }
    }
  ]
}

配置说明：

• "url"：调试目标地址，即 npm start 启动的 dev server。如果你通过 HOST 或 PORT 环境变量调整过开发服务器（参见 Advanced Configuration），这里的 URL 也要相应修改；
• "webRoot"：指向 src 目录，告诉调试器源码根在哪里；
• "sourceMapPathOverrides"：把 Webpack 打包后 source map 中的虚拟路径 webpack:///src/* 映射回磁盘上的 ${webRoot}/*，这是断点能正确落在源码行上的关键。

操作流程：运行 npm start 启动应用，然后在 VS Code 中按 F5 或点击绿色调试图标开始调试。之后你就可以在编辑器里设置断点、修改代码、单步调试修改后的代码——全程不离开编辑器。

WebStorm

要求安装 WebStorm 以及 Chrome 浏览器中的 JetBrains IDE Support 扩展。

操作路径：WebStorm 菜单 Run 中选择 Edit Configurations...，点击 + 新建 JavaScript Debug 配置，在 URL 字段填入 http://localhost:3000 并保存。如果你调整过 HOST 或 PORT 环境变量（参见 Advanced Configuration），同样需要修改该 URL。

启动：运行 npm start，然后按 ^D（macOS）或 F9（Windows/Linux），或点击绿色调试图标开始调试。同样的方式也适用于 IntelliJ IDEA Ultimate、PhpStorm、PyCharm Pro 和 RubyMine。

自动格式化代码

Prettier 是一个有主见的（opinionated）代码格式化工具，支持 JavaScript、CSS 和 JSON，可以把你在项目中写的代码自动格式化为统一风格。

要在 git 提交（commit）时自动格式化代码，需要安装以下依赖：

npm install --save husky lint-staged prettier

或者使用 yarn：

yarn add husky lint-staged prettier

三个依赖各自的职责：

• husky：让 git hooks 可以像 npm scripts 一样使用；
• lint-staged：只对 git 暂存区（staged files）中的文件运行脚本，避免全量扫描；
• prettier：提交前要执行的 JavaScript 格式化器。

然后在项目根目录的 package.json 中加入以下字段：

+  "husky": {
+    "hooks": {
+      "pre-commit": "lint-staged"
+    }
+  }

接着再加一个 lint-staged 字段，例如：

  "dependencies": {
    // ...
  },
+ "lint-staged": {
+   "src/**/*.{js,jsx,ts,tsx,json,css,scss,md}": [
+     "prettier --write"
+   ]
+ },
  "scripts": {

这样，每次提交时 Prettier 都会自动格式化被修改的文件。首次初始化整个项目的格式，可以直接运行：

./node_modules/.bin/prettier --write "src/**/*.{js,jsx,ts,tsx,json,css,scss,md}"

如需在编辑器内集成 Prettier（保存时自动格式化），请按 Prettier 官方文档中的 Editor Integration 部分配置你使用的编辑器。

小结

• 语法高亮与 Lint 显示都围绕"让编辑器理解 CRA 的 Babel/ESLint 工具链"展开，且编辑器端的 lint 插件只影响编辑器，不影响构建期 lint；
• eslintConfig 的默认值是 { "extends": "react-app" }，扩展时保留 "react-app"、TS 规则走 overrides、"error" 级规则会阻断构建，这三点是自定义规则的安全底线；
• 调试配置的三个核心是 url、webRoot、sourceMapPathOverrides，分别对应 dev server 地址、源码根目录和 Webpack 虚拟路径到磁盘路径的映射；
• 格式化链路是 husky（挂 pre-commit）→ lint-staged（限定暂存文件）→ prettier --write（执行格式化），三者各司其职。