Gatsby 中配置与自定义 ESLint：内置规则、快速刷新约束与自定义配置实战

Gatsby 中配置与自定义 ESLint：内置规则、快速刷新约束与自定义配置实战

【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby

导读

ESLint 是 JavaScript 生态中应用最广的静态代码检查工具，能够在不执行代码的前提下发现语法错误、潜在缺陷与不符合团队规范的模式。Gatsby 在构建管线中内置了一套开箱即用的 ESLint 配置，本文以 Gatsby 仓库中 eslint.md 文档为骨架，结合 eslint-config.ts、webpack-utils.ts 与 webpack.config.js 等源码，系统讲解内置 ESLint 的组成、如何用自定义.eslintrc接管检查、以及如何彻底关闭 ESLint。读完本文，你将掌握在 Gatsby 项目中启用、定制与关闭 ESLint 的完整方案，并理解底层ESLintPlugin的加载逻辑。

ESLint 在 Gatsby 项目中的作用

JavaScript 是一门动态、弱类型语言，尤其容易在开发期埋下隐患。由于没有编译期检查，语法或逻辑错误通常要等代码实际执行才能暴露。ESLint 这类 lint 工具通过静态分析（static analysis）在运行前发现"有问题的模式"（problematic patterns），显著降低排错成本。ESLint 本身是开源项目，除 JavaScript 外，社区也为绝大多数编程语言提供了 linter，部分编译器甚至会把 lint 能力内置进编译流程。

在 Gatsby 中，ESLint 的价值集中体现在两个层面：

1. 开发体验：将检查结果实时输出到运行gatsby develop的终端，以及浏览器开发者工具的 console 中，让开发者对刚保存的文件获得即时反馈。
2. 框架约束：通过两条特殊的"必选规则"保障 React Fast Refresh 的正常工作，防止页面模板以匿名方式导出导致组件局部状态丢失。

Gatsby 内置 ESLint 配置的组成

Gatsby 的默认 ESLint 配置定义在 packages/gatsby/src/utils/eslint-config.ts 中，导出两个关键对象：

• eslintConfig(usingAutomaticJsxRuntime)：完整的开发/构建用配置，基于eslint-config-react-app（Create React App 官方共享配置）叠加了海量jsx-a11y无障碍规则。
• eslintRequiredConfig：仅包含两条 Fast Refresh 必选规则的极简配置，通过 eslint/required.js 引入：
  • no-anonymous-exports-page-templates（warn）
  • limited-exports-page-templates（warn）

两条规则的实现位于 packages/gatsby/src/utils/eslint-rules/ 目录。以 no-anonymous-exports-page-templates.ts 为例：它只针对页面模板（通过isPageTemplate判断）检查ExportDefaultDeclaration，若默认导出的箭头函数、函数声明或类声明是匿名的，就提示开发者给组件命名——因为匿名导出会导致 Fast Refresh 无法保留本地组件状态，其报错信息甚至会给出 Before/After 修正示例。

完整配置还设置了一批全局变量与解析器选项：

globals: { graphql: true, __PATH_PREFIX__: true, __TRAILING_SLASH__: true, __BASE_PATH__: true, }, parser: require.resolve(`@babel/eslint-parser`), parserOptions: { ecmaVersion: 2020, sourceType: `module`, ecmaFeatures: { jsx: true }, babelOptions: { presets: [require.resolve(`babel-preset-gatsby`)] }, requireConfigFile: false, },

其中@babel/eslint-parser配合babel-preset-gatsby解析 JSX 与 Babel 语法；react/jsx-uses-react与react/react-in-jsx-scope会根据jsxRuntime是否为automatic自动关闭（新 JSX 运行时无需在作用域内引入 React）。

内置配置如何进入构建管线

eslintConfig与eslintRequiredConfig由 packages/gatsby/src/utils/webpack-utils.ts 封装为两个 webpack 插件工厂plugins.eslint与plugins.eslintRequired，二者都基于ESLintPlugin，检查范围限定为js/jsx扩展名，并排除node_modules、bower_components及虚拟模块目录。

真正决定加载哪套配置的判断逻辑在 packages/gatsby/src/utils/webpack.config.js：

const isCustomEslint = hasLocalEslint(program.directory) // if no local eslint config, then add gatsby config if (!isCustomEslint) { configPlugins.push(plugins.eslint()) } // Enforce fast-refresh rules even with local eslint config if (isCustomEslint) { configPlugins.push(plugins.eslintRequired()) }

即：项目里没有自定义 ESLint 配置时加载完整内置配置；有自定义配置时加载仅含两条必选规则的极简配置。hasLocalEslint的判定实现于 packages/gatsby/src/utils/local-eslint-config-finder.ts：先检查package.json中是否有eslintConfig字段，再用 glob 匹配项目根目录下的.eslintrc?(.js|.json|.yaml|.yml)文件。

如何自定义 ESLint 配置

对大多数用户而言，内置配置已经足够。但如果你所在的公司有自己的一套 ESLint 规范，需要叠加额外的 preset、plugin 或 rule，可以按以下步骤接管 ESLint 配置。

1. 安装依赖

# First install the necessary ESLint dependencies npm install --save-dev eslint-config-react-app

eslint-config-react-app是内置配置的基础，自定义时以它为起点可以最大程度保留 Gatsby 默认的检查行为。

2. 创建配置文件

在站点根目录创建.eslintrc.js：

# Create a config file for ESLint touch .eslintrc.js

只要项目根目录出现.eslintrc.js（或.eslintrc.json、.eslintrc.yaml、.eslintrc.yml，以及package.json中的eslintConfig字段），hasLocalEslint就会判定为"存在自定义配置"，进而触发plugins.eslintRequired()分支。

3. 编写配置内容

将以下片段复制到.eslintrc.js，再按需追加 preset、plugin 和 rule：

module.exports = { globals: { __PATH_PREFIX__: true, }, extends: `react-app`, }

__PATH_PREFIX__是 Gatsby 注入的全局变量，用于在页面中拼接路径前缀；声明为全局可避免no-undef误报。需要更多 Gatsby 全局变量时，可对照内置配置补上graphql、__TRAILING_SLASH__、__BASE_PATH__。

4. 自定义配置后发生了什么

这一点至关重要：当存在自定义.eslintrc文件时，Gatsby 会完全覆盖（overwrite）内置的eslintConfig，内置的eslint-config-react-app与全部jsx-a11y规则将不再生效。此时plugins.eslintRequired()加载的eslintRequiredConfig仅保留两条必选规则：

• no-anonymous-exports-page-templates：禁止页面模板匿名导出
• limited-exports-page-templates：限制页面模板的导出内容

其余规则全部需要你自行激活。有两个推荐的补救途径：

1. 复制内置规则：将 eslint-config.ts 中的extends、rules等复制到本地.eslintrc.js，再在此基础上增删。
2. 使用社区插件：官方文档推荐引入社区插件gatsby-plugin-eslint来接入你自定义的 ESLint 工作流（详见仓库 plugins 目录 中关于自定义插件的说明）。

关于自定义配置的注意事项

自定义配置接管后，内置的eslint-loader行为也会随之变化。默认情况下（无任何 ESLint 文件时），Gatsby 隐式添加一个"极简版" ESLint loader，把检查反馈同时输出到运行gatsby develop/gatsby build的终端窗口和浏览器开发者工具 console，让你在保存文件后立刻获得聚合反馈。一旦你提供了自定义.eslintrc，Gatsby 认为检查由你全权负责，这个默认 loader 即被覆盖停用，仅保留上述两条必选规则的输出。

如何禁用 ESLint

如果你希望彻底关闭站点的 ESLint 检查，只需在项目根目录创建一个空的.eslintrc文件：

touch .eslintrc

空文件同样会被hasLocalEslint识别为自定义配置，从而停用内置的eslint-loader及完整内置配置。但请务必注意：两条与 Fast Refresh 相关的必选规则仍然会激活，并继续显示在终端输出中。原因在源码中写得很清楚——webpack.config.js中if (isCustomEslint) configPlugins.push(plugins.eslintRequired())这一分支是无条件的：只要有自定义配置（哪怕是空文件），eslintRequired插件就会加载，以保证页面模板的导出方式不会破坏 Fast Refresh 的组件状态保留机制。

换言之，在 Gatsby 中无法通过配置彻底关掉这两条规则，它们是框架为开发体验（React Fast Refresh）设置的最底线保护。

内置规则速查与参考

• 默认规则集：eslint-config-react-app（见 eslint-config.ts）+ 约 30 条jsx-a11y无障碍规则（alt-text、anchor-is-valid、heading-has-content、media-has-caption等，均为warn级别）。
• 必选规则集：两条 Fast Refresh 规则，实现与测试分别位于 eslint-rules/ 与 eslint-rules/tests/。
• 配置探测：hasLocalEslint（local-eslint-config-finder.ts）同时支持.eslintrc*文件与package.json#eslintConfig两种形式。
• 相关文档：Fast Refresh、JavaScript 工具链。

总结

Gatsby 的 ESLint 体系遵循一条清晰的分层设计：无自定义配置时，全量内置规则守护你的代码；有自定义配置（哪怕是空文件）时，框架自动退守到两条 Fast Refresh 必选规则。理解这一机制，你就既能享受开箱即用的检查体验，又能在团队规范需要时平滑地接管 ESLint 配置，同时不会牺牲 Fast Refresh 带来的热更新体验。

【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby