本文详解如何在非 typescript 的 nuxt 3 项目中正确配置 eslint，使其识别 `auto-imports`（如 `definepage`, `useruntimeconfig`, `ref` 等），彻底解决 `no-undef` 报错问题。关键在于组合 `@antfu/eslint-config`、volar takeover 模式及 nuxt 类型生成机制。
要在 Nuxt 3 中让 ESLint 无缝支持自动导入（auto-imports）——例如直接使用 definePage、useRoute、computed 而不报 no-undef 错误——核心不在于手动声明全局变量，而在于让 ESLint 理解 Nuxt 自动生成的类型上下文。即使你未使用 TypeScript，Nuxt 3 仍会在 .nuxt 目录下生成类型声明（.nuxt/types/auto-imports.d.ts），ESLint（配合 Volar）可据此推断全局可用标识符。
✅ 推荐精简配置方案（经验证适用于纯 JavaScript Nuxt 3 项目）：
1. 安装依赖
仅需两个关键包（无需 @nuxt/eslint-config 等已弃用或不兼容的配置）：
npm install -D eslint @antfu/eslint-config@^0.42.0 # 或使用 pnpm pnpm add -D eslint @antfu/eslint-config@^0.42.0
2. 配置 .eslintrc.js
采用极简继承策略，@antfu 预设已内置对 Vue、Nuxt、Unplugin Auto-imports 的深度支持：
// .eslintrc.js
module.exports = {
extends: ['@antfu'],
// 可选：显式启用 JS 支持（若项目含 .mjs/.cjs）
parserOptions: {
ecmaVersion: 'latest',
},
}3. VS Code 关键设置（.vscode/settings.json）
确保 ESLint 和 Volar 协同工作：
{
"editor.formatOnSave": false,
"editor.codeActionsOnSave": {
"source.fixAll.eslint": true
},
"eslint.options": {
"extensions": [".js", ".vue"]
},
// ⚠️ 必须启用 Volar Takeover 模式（禁用内置 Vue 插件）
"vue.preferences.useVolarForVue2": false,
"typescript.preferences.includePackageJsonAutoImports": "auto"
}4. 启动 Nuxt 开发服务器（关键一步！）
运行一次 nuxt dev（或 npm run dev）：
nuxt dev
此举会触发 Nuxt 在 .nuxt/types/auto-imports.d.ts 中生成完整的自动导入类型声明。ESLint 和 Volar 均依赖此文件进行符号解析。首次运行后，重启 VS Code 窗口（或重新加载窗口 Ctrl+Shift+P → Developer: Reload Window）。
5. 验证 Volar 处于 Takeover 模式
- 打开任意 .vue 文件 → 查看右下角状态栏
- 应显示 Volar (Takeover)（而非 Volar 或 Vue Language Features）
- 若未启用：点击状态栏 → 选择 Switch to Takeover Mode
- ✅ 此模式下，Volar 将接管 .js/.vue 的类型检查与自动补全，ESLint 通过 @antfu 配置间接消费其类型信息。
? 常见误区与注意事项：
- ❌ 不要手动在 globals 中罗列 definePage, useAsyncData 等 —— 这是临时补丁，无法支持类型推导和 IDE 补全；
- ❌ 避免混用 @nuxtjs/eslint-config 等旧版配置，它们未适配 Nuxt 3 的模块化架构；
- ✅ @antfu/eslint-config 内置了 eslint-plugin-vue、eslint-plugin-jsx-a11y 及 Nuxt 特定规则（如 vue/multi-word-component-names），无需额外扩展；
- ✅ 若使用 Prettier，建议通过 @antfu/eslint-config 的 prettier 预设集成（它已处理格式化冲突）；
- ? 修改 nuxt.config.ts/js 或新增插件后，建议重启 nuxt dev 以更新 .nuxt/types/ 下的声明文件。
完成以上步骤后，你在 <script setup> 或 .js 文件中直接使用 useFetch, useState, definePage 等将不再触发 no-undef，且获得完整的参数提示与类型跳转能力——真正实现「零配置感知」的自动导入开发体验。</script>
