为 TypeScript/React 项目配置…

当需要为 TypeScript/React（或 Node.js）项目搭建或统一 ESLint + Prettier 的代码检查与格式化配置时使用。

适用场景

解决思路

1. 安装依赖：ESLint、Prettier 及相关插件（@eslint/js、@typescript-eslint/eslint-plugin、@typescript-eslint/parser、eslint-plugin-react、eslint-plugin-react-hooks、eslint-plugin-react-refresh、eslint-plugin-import、eslint-config-prettier 等）。
2. 配置 ESLint：使用 v9+ 的 flat config（eslint.config.mjs），先设置 ignores 忽略 node_modules、dist、build、.next、coverage、*.config.js、*.config.mjs。
3. 在 flat config 中引入 js.configs.recommended 作为基础 JavaScript 配置。
4. 为 **/*.ts 和 **/*.tsx 配置 TypeScript 解析器 tsParser，parserOptions 设置 ecmaVersion: 'latest'、sourceType: 'module'、ecmaFeatures.jsx: true、project: './tsconfig.json'。
5. 为 TypeScript 文件启用 @typescript-eslint 与 import 插件，并配置规则：no-unused-vars（argsIgnorePattern/varsIgnorePattern 为 ^_）、no-explicit-any 为 warn、explicit-function-return-type 与 explicit-module-boundary-types 关闭、no-non-null-assertion 为 warn、consistent-type-imports 为 error（prefer: type-imports，fixStyle: inline-type-imports）。
6. 配置 import 规则：import/order 按 builtin、external、internal、parent/sibling、index、type 分组，newlines-between: always，alphabetize 按 asc 且忽略大小写；import/no-duplicates 为 error。
7. 为 **/*.tsx 和 **/*.jsx 配置 React 插件（react、react-hooks、react-refresh），settings.react.version 设为 detect。
8. 配置 React 规则：react/react-in-jsx-scope 关闭、react/prop-types 关闭、react/jsx-uses-react 关闭、react/jsx-no-target-blank 为 error、react/self-closing-comp 为 error、react/jsx-curly-brace-presence 为 error（props 与 children 均为 never）、react-hooks/rules-of-hooks 为 error、react-hooks/exhaustive-deps 为 warn、react-refresh/only-export-components 为 warn（allowConstantExport: true）。
9. 为测试文件（**/*.test.ts、**/*.test.tsx、**/*.spec.ts、**/*.spec.tsx）关闭 no-explicit-any 与 no-non-null-assertion。
10. 在配置末尾引入 eslint-config-prettier（prettier）以禁用与 Prettier 冲突的规则。
11. 若使用旧版配置，则改用 .eslintrc.json：设置 root: true，env 包含 browser、es2022、node，extends 依次为 eslint:recommended、@typescript-eslint/recommended、@typescript-eslint/recommended-type-checked、react/recommended、react-hooks/recommended、import/recommended、import/typescript、jsx-a11y/recommended、prettier。
12. 旧版配置中设置 parser 为 @typescript-eslint/parser，parserOptions 含 ecmaVersion: latest、sourceType: module、ecmaFeatures.jsx: true、project: ['./tsconfig.json']，plugins 含 @typescript-eslint、react、react-hooks、import、jsx-a11y。
13. 旧版配置中设置 settings：react.version 为 detect，import/resolver.typescript.alwaysTryTypes 为 true。
14. 旧版配置规则：no-unused-vars（^_ 忽略）、consistent-type-imports、no-explicit-any 为 warn、no-floating-promises 为 error、await-thenable 为 error、react/react-in-jsx-scope 关闭、react/prop-types 关闭、react/self-closing-comp 为 error、import/order 分组排序、import/no-duplicates 为 error、import/no-unresolved 为 error、no-console 为 warn（allow: warn、error）、prefer-const 为 error、no-var 为 error。
15. 旧版配置用 overrides 对测试文件关闭 no-explicit-any 与 no-floating-promises，并用 ignorePatterns 忽略 node_modules、dist、build、.next、coverage。
16. 创建 .prettierrc：semi: true、singleQuote: true、trailingComma: 'es5'、tabWidth: 2、useTabs: false、printWidth: 100、bracketSpacing: true、bracketSameLine: false、arrowParens: 'always'、endOfLine: 'lf'、quoteProps: 'as-needed'、jsxSingleQuote: false、proseWrap: 'preserve'、htmlWhitespaceSensitivity: 'css'、embeddedLanguageFormatting: 'auto'。
17. 创建 .prettierignore：node_modules、dist、build、.next、coverage、*.min.js、*.min.css、pnpm-lock.yaml、package-lock.json、yarn.lock。
18. 在 package.json 中添加脚本：lint（eslint . --ext .ts,.tsx --max-warnings 0）、lint:fix（eslint . --ext .ts,.tsx --fix）、format（prettier --write "**/*.{ts,tsx,json,md,css}"）、format:check（prettier --check "**/*.{ts,tsx,json,md,css}"）、typecheck（tsc --noEmit）、check（依次运行 typecheck、lint、format:check）。
19. 安装 Husky 与 lint-staged（npm install -D husky lint-staged；npx husky init）。
20. 在 package.json 配置 lint-staged：*.{ts,tsx} 执行 eslint --fix --max-warnings 0 与 prettier --write；*.{json,md,css,scss} 执行 prettier --write。
21. 创建 .husky/pre-commit 内容为 npx lint-staged；创建 .husky/commit-msg 内容为 npx commitlint --edit $1。
22. 配置 commitlint.config.js：extends @commitlint/config-conventional，type-enum 限定 feat、fix、docs、style、refactor、perf、test、build、ci、chore、revert，subject-case 为 lower-case，subject-max-length 为 72，body-max-line-length 为 100。
23. 配置 .vscode/settings.json：editor.formatOnSave 为 true、默认格式化器为 esbenp.prettier-vscode、codeActionsOnSave 中 source.fixAll.eslint 为 explicit 且 source.organizeImports 为 never，为 typescript、typescriptreact、json 指定 Prettier 格式化器，eslint.validate 包含 javascript、javascriptreact、typescript、typescriptreact，typescript.preferences.importModuleSpecifier 为 relative，typescript.suggest.autoImports 为 true。
24. 配置 .vscode/extensions.json 推荐 dbaeumer.vscode-eslint、esbenp.prettier-vscode、bradlc.vscode-tailwindcss、streetsidesoftware.code-spell-checker。
25. Next.js 项目使用 .eslintrc.js：extends 为 next/core-web-vitals、plugin:@typescript-eslint/recommended、prettier，parser 为 @typescript-eslint/parser，plugins 为 @typescript-eslint，并配置 no-unused-vars、consistent-type-imports、import/order 规则。
26. Node.js/API 项目使用 flat config：引入 eslint-plugin-n，配置 n/no-process-exit 为 error、n/no-unsupported-features/es-syntax 关闭、no-floating-promises 为 error、require-await 为 error，最后引入 prettier。
27. 如需自定义规则，编写 ESLint 插件规则（如 no-direct-env），通过 meta 定义 type、docs、messages，在 create 中监听 MemberExpression 检测 process.env 直接访问并 report。
28. 遵循最佳实践：extends 顺序要谨慎、启用类型感知规则、强制 import 排序、始终把 prettier 放在 extends 最后、配置保存时自动修复、使用 pre-commit 钩子、在 CI 中运行 lint、渐进式采用（先从 warn 开始）。
29. 按输出清单核对：ESLint 配置（flat 或 legacy）、TypeScript-ESLint 集成、React/React Hooks 规则、import 排序规则、Prettier 配置、ESLint-Prettier 集成、VS Code 设置、Husky pre-commit 钩子、lint-staged 配置、CI lint 校验、忽略模式、lint/format 的 npm 脚本。

适用边界 · 注意事项

• 项目不使用 TypeScript 或 React 时，无需引入对应的解析器、插件与规则集。
• 项目已使用其他成熟的 lint/format 方案（如 Biome、oxlint）时，不必再叠加 ESLint + Prettier。
• 仅需临时格式化少量文件、不打算长期维护配置时，直接使用编辑器格式化即可。