Nuxt 代码风格实战nuxt/eslint 与 Flat Config 的规范落地全解【免费下载链接】nuxtthe full-stack Vue framework项目地址: https://gitcode.com/GitHub_Trending/nu/nuxt本篇围绕 Nuxt 官方的代码风格Code Style指南展开Nuxt 开箱即用地支持 ESLint官方推荐通过nuxt/eslint模块为项目生成项目感知project-aware的 ESLint 配置。读完本文你将掌握 Nuxt 项目接入 ESLint 的标准流程flat config 格式、快速接入命令、eslint.config.mjs生成机制并能参考 Nuxt 仓库自身根目录的 eslint.config.mjs 完整案例学会用流畅式构建器 API 定制规则区块、目录级规则覆盖与模块边界约束。一、核心结论Nuxt 对 ESLint 的原生支持Nuxt 对代码风格的官方建议可以概括为一句话用nuxt/eslint模块启用 ESLint 支持它会自动为你搭建一套与项目感知了解 Nuxt 目录结构、自动导入、Vue 与 TypeScript 生态匹配的 ESLint 配置而不是让你在裸的 ESLint 配置上从零拼规则。该指南同时给出了一个重要的版本前提见 代码风格文档nuxt/eslint模块面向ESLint flat config扁平化配置格式设计这也是ESLint v9 起的默认配置格式如果你仍在使用旧版.eslintrc系列配置则需要使用nuxt/eslint-config手动进行配置官方强烈建议迁移到 flat config 以保证未来兼容。也就是说Nuxt 生态在代码风格上的官方路径是nuxt/eslint模块推荐 flat configeslint.config.mjsnuxt/eslint-config遗留配置的兜底方案。二、快速接入Quick Setup按照指南在 Nuxt 项目根目录执行npx nuxt module add eslint该命令会把nuxt/eslint注册到项目的模块列表。接下来启动你的 Nuxt 应用项目根目录下会生成一个eslint.config.mjs文件。你可以在此基础上按需定制规则——这正是 Nuxt 仓库自身采用的做法下面以其为例深入拆解。三、Flat Config 实战拆解 Nuxt 仓库自身的 eslint.config.mjsNuxt 仓库根目录的 eslint.config.mjs 是一份非常完整的 flat config 生产级案例它完整展示了createConfigForNuxt提供的能力基础特性开关、全局忽略、分区块规则覆盖、按目录追加规则、以及配置类型生成。3.1 入口createConfigForNuxt与特性开关配置入口是一个流畅式fluent构建器通过features选项声明启用的规则族import { createConfigForNuxt } from nuxt/eslint-config/flat export default createConfigForNuxt({ features: { stylistic: { commaDangle: always-multiline, }, tooling: true, typescript: true, }, })其中stylistic启用样式/格式化类规则并支持细粒度覆盖如commaDangle: always-multiline表示多行表达式必须带尾逗号typescript: true启用 TypeScript 专属规则族typescript-eslint/*tooling: true启用面向工具链的规则如 unicorn 等插件的规则集。返回值是一个链式构建器后续通过.prepend()/.override()/.append()/.onResolved()组合出最终配置。3.2.prepend()全局忽略与语言选项Nuxt 仓库把全局忽略单独放在一个对象里并前置flat config 要求忽略项必须是独立的配置对象才会被识别为全局忽略.prepend({ // Ignores have to be a separate object to be treated as global ignores // Dont add other attributes to this object ignores: [ .goff/**, packages/schema/schema/**, packages/nuxt/stubs/**, packages/nuxt/src/app/components/welcome.vue, packages/nuxt/src/app/components/error-*.vue, // ... 模板生成文件、类型测试夹具等 ], }, { languageOptions: { globals: { $fetch: readonly, NodeJS: readonly, }, }, name: local/settings, settings: { /* jsdoc 设置 */ }, })两个值得借鉴的细节全局ignores单独成对象注释明确说明忽略必须作为独立对象才会被当作全局忽略处理不要往该对象里加其他属性——这是 flat config 与旧.eslintrc的关键差异之一声明全局变量$fetch是 Nuxt 自动导入的客户端请求函数将其声明为readonly全局可避免no-undef误报。3.3.override()按命名区块覆盖规则nuxt/eslint生成的配置是分区块命名的如nuxt/javascript、nuxt/typescript/rules、nuxt/stylistic、nuxt/tooling/unicorn、nuxt/vue/rules你可以精确地只覆盖某个区块而不影响其他区块。Nuxt 仓库的实践包括JavaScript 基础规则.override(nuxt/javascript, ...)见 eslint.config.mjsrules: { curly: [error, all], // Including if blocks with a single statement dot-notation: error, logical-assignment-operators: [error, always, { enforceForIfStatements: true }], no-console: [warn, { allow: [warn, error, debug] }], no-lonely-if: error, // No single if in an else block no-useless-rename: error, object-shorthand: error, prefer-const: [error, { destructuring: any, ignoreReadBeforeAssign: false }], require-await: error, sort-imports: [error, { ignoreDeclarationSort: true }], },可以看到典型的团队级约束风格单语句if也必须加大括号、禁止孤立if挂在else里、no-console降级为warn但白名单放行warn/error/debug、强制prefer-const与require-await。TypeScript 规则.override(nuxt/typescript/rules, ...)见 eslint.config.mjsrules: { typescript-eslint/ban-ts-comment: [ error, { ts-expect-error: allow-with-description, ts-ignore: true }, ], typescript-eslint/no-unused-vars: [ error, { argsIgnorePattern: ^_, destructuredArrayIgnorePattern: ^_, ignoreRestSiblings: true, varsIgnorePattern: , }, ], // ... },argsIgnorePattern: ^_是常见的以下划线开头的未用参数不报错约定ts-expect-error要求附带描述兼顾了类型压制与代码可维护性。Stylistic 与工具链规则.override(nuxt/tooling/unicorn, { rules: { unicorn/no-new-array: off, unicorn/prefer-dom-node-text-content: off, }, }) .override(nuxt/stylistic, { rules: { stylistic/brace-style: [error, 1tbs, { allowSingleLine: true }], stylistic/quote-props: [error, consistent], stylistic/space-before-function-paren: [error, always], // ... }, })3.4.append()按目录追加自定义规则这是大型仓库中最有参考价值的部分——通过files匹配特定目录追加与业务架构强绑定的规则。Nuxt 仓库追加的规则覆盖了以下几类场景1. 强制显式 Node.js 导入local/requires/explicit-node-imports见 eslint.config.mjsrules: { no-restricted-globals: [ error, { message: Use explicit import: import process from node:process ... Implicit globals are banned for clarity and tree-shakability., name: process, }, { message: Use explicit import: import { performance } from node:perf_hooks ..., name: performance, }, ], }规则意图在错误信息中写明隐式全局变量不利于可读性与 tree-shaking必须import process from node:process。2. 用import-x划定模块边界local/rules见 eslint.config.mjsimport-x/no-restricted-paths: [ error, { zones: [ { from: packages/nuxt/src/!(core)/runtime/*, message: core should not directly import from modules., target: packages/nuxt/src/core }, { from: packages/nuxt/src/!(app)/**/*, message: app should not directly import from modules., target: packages/nuxt/src/app }, { from: packages/nitro, message: nitro should not directly import other packages., target: packages/!(nitro)/**/* }, ], }, ],zones的from/target组合把架构分层core / app / modules / nitro 之间不允许反向或越层引用固化为 ESLint 错误CI 中任何违规导入都会直接报错——这是用 lint 规则守架构的典型写法。3. 构建期告警统一走 diagnosticslocal/requires/nostics-diagnostics见 eslint.config.mjsno-restricted-syntax: [error, { message: Use a nostics diagnostic (see packages/kit/src/diagnostics/) instead of logger/console for build-time warnings and errors., selector: CallExpression[callee.object.name/^(logger|console)$/][callee.property.name/^(warn|error)$/], }],通过 AST 选择器精准拦截logger.warn/error与console.warn/error调用强制各构建模块使用 Nuxt Kit 的 diagnostics 目录packages/kit/src/diagnostics/输出结构化诊断信息。4. 测试与文档场景的定向放宽测试文件启用eslint-plugin-no-only-tests防止it.only被误提交no-only-tests/no-only-tests: error对test/**目录关闭no-console、typescript-eslint/no-explicit-any对 fixtures 目录放宽vue/multi-word-component-names、vue/valid-v-for等对测试夹具过于苛刻的规则文档目录**/*.md通过eslint/markdown处理器接入 lint同时针对 markdown 代码块**/*.md/**/*放宽no-unused-vars等规则——Nuxt 的文档本身也是被 lint 的对象对**/eslint.config.mjs自身启用perfectionist/sort-objects强制配置文件内规则键按字母排序。5. 配置类型生成.onResolved(configs typegen(configs))链尾通过eslint-typegen在配置解析完成后生成 ESLint 配置的类型定义让配置对象在编辑器中获得类型提示——这也是 flat config 生态相比旧格式的一个优势点。四、把 Lint 纳入工程流程Nuxt 仓库根 package.json 的scripts展示了完整的 lint 工作流lint: eslint . --cache, lint:fix: eslint . --cache --fix, lint:docs: markdownlint --ignore-path.gitignore ./docs case-police docs/**/*.md *.md eslint docs --cache, lint:docs:fix: markdownlint --ignore-path.gitignore ./docs --fix case-police docs/**/*.md *.md --fix eslint docs --cache --fix, lint:knip: knip几个要点eslint . --cache使用缓存加速增量检查--fix自动修复可修复项lint:docs在代码 lint 之外叠加markdownlint校验文档格式与case-police校验文档文件命名大小写并单独对docs目录跑一遍 ESLint对应上文 markdown processor 的配置依赖管理上eslint、nuxt/eslint-config、eslint/markdown、eslint-plugin-perfectionist、eslint-typegen等均以 pnpm workspace 的catalog:协议集中声明版本见 package.json 的 devDependencies保证 monorepo 内 ESLint 生态版本一致。五、迁移与适用前提结合指南与仓库实际配置落地时需注意ESLint 版本nuxt/eslint模块面向 flat config即 ESLint v9 的默认格式新装项目直接npx nuxt module add eslint即可旧项目.eslintrc需要基于nuxt/eslint-config手动配置官方建议尽快迁移到 flat config定制方式模块启动时生成的eslint.config.mjs只是起点真正的定制手段是本文第三节拆解的.prepend/.override/.append链式 API——优先用override修改具名区块nuxt/javascript、nuxt/stylistic等用append追加与目录/架构绑定的自定义规则文档与工程脚本如果项目也有成体系的 docs 目录可参考 Nuxt 仓库lint:docs的做法把 markdown 校验纳入 CI。综上Nuxt 的官方代码风格路线是模块生成 flat config 分区块定制nuxt/eslint提供项目感知的默认配置骨架而 Nuxt 仓库自身的 eslint.config.mjs 则示范了如何在此骨架上叠加全局忽略、目录级规则、模块边界守护与架构约束构成一套可直接复用的代码规范工程实践。【免费下载链接】nuxtthe full-stack Vue framework项目地址: https://gitcode.com/GitHub_Trending/nu/nuxt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Nuxt 代码风格实战：@nuxt/eslint 与 Flat Config 的规范落地全解
Nuxt 代码风格实战nuxt/eslint 与 Flat Config 的规范落地全解【免费下载链接】nuxtthe full-stack Vue framework项目地址: https://gitcode.com/GitHub_Trending/nu/nuxt本篇围绕 Nuxt 官方的代码风格Code Style指南展开Nuxt 开箱即用地支持 ESLint官方推荐通过nuxt/eslint模块为项目生成项目感知project-aware的 ESLint 配置。读完本文你将掌握 Nuxt 项目接入 ESLint 的标准流程flat config 格式、快速接入命令、eslint.config.mjs生成机制并能参考 Nuxt 仓库自身根目录的 eslint.config.mjs 完整案例学会用流畅式构建器 API 定制规则区块、目录级规则覆盖与模块边界约束。一、核心结论Nuxt 对 ESLint 的原生支持Nuxt 对代码风格的官方建议可以概括为一句话用nuxt/eslint模块启用 ESLint 支持它会自动为你搭建一套与项目感知了解 Nuxt 目录结构、自动导入、Vue 与 TypeScript 生态匹配的 ESLint 配置而不是让你在裸的 ESLint 配置上从零拼规则。该指南同时给出了一个重要的版本前提见 代码风格文档nuxt/eslint模块面向ESLint flat config扁平化配置格式设计这也是ESLint v9 起的默认配置格式如果你仍在使用旧版.eslintrc系列配置则需要使用nuxt/eslint-config手动进行配置官方强烈建议迁移到 flat config 以保证未来兼容。也就是说Nuxt 生态在代码风格上的官方路径是nuxt/eslint模块推荐 flat configeslint.config.mjsnuxt/eslint-config遗留配置的兜底方案。二、快速接入Quick Setup按照指南在 Nuxt 项目根目录执行npx nuxt module add eslint该命令会把nuxt/eslint注册到项目的模块列表。接下来启动你的 Nuxt 应用项目根目录下会生成一个eslint.config.mjs文件。你可以在此基础上按需定制规则——这正是 Nuxt 仓库自身采用的做法下面以其为例深入拆解。三、Flat Config 实战拆解 Nuxt 仓库自身的 eslint.config.mjsNuxt 仓库根目录的 eslint.config.mjs 是一份非常完整的 flat config 生产级案例它完整展示了createConfigForNuxt提供的能力基础特性开关、全局忽略、分区块规则覆盖、按目录追加规则、以及配置类型生成。3.1 入口createConfigForNuxt与特性开关配置入口是一个流畅式fluent构建器通过features选项声明启用的规则族import { createConfigForNuxt } from nuxt/eslint-config/flat export default createConfigForNuxt({ features: { stylistic: { commaDangle: always-multiline, }, tooling: true, typescript: true, }, })其中stylistic启用样式/格式化类规则并支持细粒度覆盖如commaDangle: always-multiline表示多行表达式必须带尾逗号typescript: true启用 TypeScript 专属规则族typescript-eslint/*tooling: true启用面向工具链的规则如 unicorn 等插件的规则集。返回值是一个链式构建器后续通过.prepend()/.override()/.append()/.onResolved()组合出最终配置。3.2.prepend()全局忽略与语言选项Nuxt 仓库把全局忽略单独放在一个对象里并前置flat config 要求忽略项必须是独立的配置对象才会被识别为全局忽略.prepend({ // Ignores have to be a separate object to be treated as global ignores // Dont add other attributes to this object ignores: [ .goff/**, packages/schema/schema/**, packages/nuxt/stubs/**, packages/nuxt/src/app/components/welcome.vue, packages/nuxt/src/app/components/error-*.vue, // ... 模板生成文件、类型测试夹具等 ], }, { languageOptions: { globals: { $fetch: readonly, NodeJS: readonly, }, }, name: local/settings, settings: { /* jsdoc 设置 */ }, })两个值得借鉴的细节全局ignores单独成对象注释明确说明忽略必须作为独立对象才会被当作全局忽略处理不要往该对象里加其他属性——这是 flat config 与旧.eslintrc的关键差异之一声明全局变量$fetch是 Nuxt 自动导入的客户端请求函数将其声明为readonly全局可避免no-undef误报。3.3.override()按命名区块覆盖规则nuxt/eslint生成的配置是分区块命名的如nuxt/javascript、nuxt/typescript/rules、nuxt/stylistic、nuxt/tooling/unicorn、nuxt/vue/rules你可以精确地只覆盖某个区块而不影响其他区块。Nuxt 仓库的实践包括JavaScript 基础规则.override(nuxt/javascript, ...)见 eslint.config.mjsrules: { curly: [error, all], // Including if blocks with a single statement dot-notation: error, logical-assignment-operators: [error, always, { enforceForIfStatements: true }], no-console: [warn, { allow: [warn, error, debug] }], no-lonely-if: error, // No single if in an else block no-useless-rename: error, object-shorthand: error, prefer-const: [error, { destructuring: any, ignoreReadBeforeAssign: false }], require-await: error, sort-imports: [error, { ignoreDeclarationSort: true }], },可以看到典型的团队级约束风格单语句if也必须加大括号、禁止孤立if挂在else里、no-console降级为warn但白名单放行warn/error/debug、强制prefer-const与require-await。TypeScript 规则.override(nuxt/typescript/rules, ...)见 eslint.config.mjsrules: { typescript-eslint/ban-ts-comment: [ error, { ts-expect-error: allow-with-description, ts-ignore: true }, ], typescript-eslint/no-unused-vars: [ error, { argsIgnorePattern: ^_, destructuredArrayIgnorePattern: ^_, ignoreRestSiblings: true, varsIgnorePattern: , }, ], // ... },argsIgnorePattern: ^_是常见的以下划线开头的未用参数不报错约定ts-expect-error要求附带描述兼顾了类型压制与代码可维护性。Stylistic 与工具链规则.override(nuxt/tooling/unicorn, { rules: { unicorn/no-new-array: off, unicorn/prefer-dom-node-text-content: off, }, }) .override(nuxt/stylistic, { rules: { stylistic/brace-style: [error, 1tbs, { allowSingleLine: true }], stylistic/quote-props: [error, consistent], stylistic/space-before-function-paren: [error, always], // ... }, })3.4.append()按目录追加自定义规则这是大型仓库中最有参考价值的部分——通过files匹配特定目录追加与业务架构强绑定的规则。Nuxt 仓库追加的规则覆盖了以下几类场景1. 强制显式 Node.js 导入local/requires/explicit-node-imports见 eslint.config.mjsrules: { no-restricted-globals: [ error, { message: Use explicit import: import process from node:process ... Implicit globals are banned for clarity and tree-shakability., name: process, }, { message: Use explicit import: import { performance } from node:perf_hooks ..., name: performance, }, ], }规则意图在错误信息中写明隐式全局变量不利于可读性与 tree-shaking必须import process from node:process。2. 用import-x划定模块边界local/rules见 eslint.config.mjsimport-x/no-restricted-paths: [ error, { zones: [ { from: packages/nuxt/src/!(core)/runtime/*, message: core should not directly import from modules., target: packages/nuxt/src/core }, { from: packages/nuxt/src/!(app)/**/*, message: app should not directly import from modules., target: packages/nuxt/src/app }, { from: packages/nitro, message: nitro should not directly import other packages., target: packages/!(nitro)/**/* }, ], }, ],zones的from/target组合把架构分层core / app / modules / nitro 之间不允许反向或越层引用固化为 ESLint 错误CI 中任何违规导入都会直接报错——这是用 lint 规则守架构的典型写法。3. 构建期告警统一走 diagnosticslocal/requires/nostics-diagnostics见 eslint.config.mjsno-restricted-syntax: [error, { message: Use a nostics diagnostic (see packages/kit/src/diagnostics/) instead of logger/console for build-time warnings and errors., selector: CallExpression[callee.object.name/^(logger|console)$/][callee.property.name/^(warn|error)$/], }],通过 AST 选择器精准拦截logger.warn/error与console.warn/error调用强制各构建模块使用 Nuxt Kit 的 diagnostics 目录packages/kit/src/diagnostics/输出结构化诊断信息。4. 测试与文档场景的定向放宽测试文件启用eslint-plugin-no-only-tests防止it.only被误提交no-only-tests/no-only-tests: error对test/**目录关闭no-console、typescript-eslint/no-explicit-any对 fixtures 目录放宽vue/multi-word-component-names、vue/valid-v-for等对测试夹具过于苛刻的规则文档目录**/*.md通过eslint/markdown处理器接入 lint同时针对 markdown 代码块**/*.md/**/*放宽no-unused-vars等规则——Nuxt 的文档本身也是被 lint 的对象对**/eslint.config.mjs自身启用perfectionist/sort-objects强制配置文件内规则键按字母排序。5. 配置类型生成.onResolved(configs typegen(configs))链尾通过eslint-typegen在配置解析完成后生成 ESLint 配置的类型定义让配置对象在编辑器中获得类型提示——这也是 flat config 生态相比旧格式的一个优势点。四、把 Lint 纳入工程流程Nuxt 仓库根 package.json 的scripts展示了完整的 lint 工作流lint: eslint . --cache, lint:fix: eslint . --cache --fix, lint:docs: markdownlint --ignore-path.gitignore ./docs case-police docs/**/*.md *.md eslint docs --cache, lint:docs:fix: markdownlint --ignore-path.gitignore ./docs --fix case-police docs/**/*.md *.md --fix eslint docs --cache --fix, lint:knip: knip几个要点eslint . --cache使用缓存加速增量检查--fix自动修复可修复项lint:docs在代码 lint 之外叠加markdownlint校验文档格式与case-police校验文档文件命名大小写并单独对docs目录跑一遍 ESLint对应上文 markdown processor 的配置依赖管理上eslint、nuxt/eslint-config、eslint/markdown、eslint-plugin-perfectionist、eslint-typegen等均以 pnpm workspace 的catalog:协议集中声明版本见 package.json 的 devDependencies保证 monorepo 内 ESLint 生态版本一致。五、迁移与适用前提结合指南与仓库实际配置落地时需注意ESLint 版本nuxt/eslint模块面向 flat config即 ESLint v9 的默认格式新装项目直接npx nuxt module add eslint即可旧项目.eslintrc需要基于nuxt/eslint-config手动配置官方建议尽快迁移到 flat config定制方式模块启动时生成的eslint.config.mjs只是起点真正的定制手段是本文第三节拆解的.prepend/.override/.append链式 API——优先用override修改具名区块nuxt/javascript、nuxt/stylistic等用append追加与目录/架构绑定的自定义规则文档与工程脚本如果项目也有成体系的 docs 目录可参考 Nuxt 仓库lint:docs的做法把 markdown 校验纳入 CI。综上Nuxt 的官方代码风格路线是模块生成 flat config 分区块定制nuxt/eslint提供项目感知的默认配置骨架而 Nuxt 仓库自身的 eslint.config.mjs 则示范了如何在此骨架上叠加全局忽略、目录级规则、模块边界守护与架构约束构成一套可直接复用的代码规范工程实践。【免费下载链接】nuxtthe full-stack Vue framework项目地址: https://gitcode.com/GitHub_Trending/nu/nuxt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考