--- title: Nuxt3 代码规范 description: 这是一份提供给AI大模型的Nuxt3框架规范、编程标准，可以有效提高Cursor等大模型对Nuxt.js框架的编写能力。 date: 2025-07-12 img: https://lijue-me.oss-cn-chengdu.aliyuncs.com/20250624125918171.png navigation: icon: simple-icons:nuxtdotjs --- ## 概述 这是一份提供给AI大模型的Nuxt3框架规范、编程标准，可以有效提高Cursor等大模型对Nuxt.js框架的编写能力。 --- description: 本规则为 Nuxt.js 项目提供全面的最佳实践和编码标准，涵盖代码组织、性能、安全性、测试和常见陷阱。旨在确保 Nuxt.js 应用程序的可维护性、可扩展性和安全性。 globs: *.vue,*.js,*.ts,*.mjs,*.mts,*.jsx,*.tsx,*.config.js,*.config.ts --- - **启用 ESLint 支持：** 使用 `@nuxt/eslint` 模块来配置项目感知的 ESLint。这确保代码质量和一致性。 - 运行 `npx nuxi module add eslint` 添加模块。 - 根据需要自定义生成的 `eslint.config.mjs` 文件。 - **采用 Nuxt.js 模块：** 利用 Nuxt.js 模块来封装功能并维护干净的代码库。在实现自定义解决方案之前先探索现有模块（例如，用于服务端身份验证的 `@nuxt/auth`）。 - **约定优于配置：** 遵循 Nuxt.js 约定来简化开发和协作。除非绝对必要，否则避免偏离约定。 - **高效利用 Nuxt 布局：** 为多个页面共享的组件创建可重用布局，以确保一致性并节省开发时间。布局位于 `layouts/` 目录中。 - **使用 Pinja 管理状态：** 使用 Pinia 进行状态管理。根据功能或特性组织 store 模块，以提高可维护性。 - **将页面分解为组件：** 将页面分解为小的、可重用的组件，以增强可维护性、可测试性和可重用性。每个组件都应该有单一责任。 - **明智地利用 Nuxt 插件：** 使用 Nuxt 插件在 Vue.js 初始化之前运行代码或添加全局功能。注意插件对性能的影响。插件位于 `plugins/` 目录中。 - **针对 SEO 和性能进行优化：** 利用 Nuxt.js 的服务端渲染 (SSR) 来优化 SEO。为图片实现懒加载并优化资源以最小化初始加载时间。使用 Lighthouse 等工具识别性能瓶颈。 - **实现错误处理和验证：** 实现强大的错误处理和验证机制，以提供无缝的用户体验。使用 Nuxt.js 中间件拦截请求和响应进行错误处理和数据验证。 - **为代码编写文档：** 使用 JSDoc 等工具为组件、模块和自定义函数提供清晰简洁的文档。 - **拥抱测试：** 使用 Jest、Vue Test Utils 和 Vitest 等工具编写单元测试、集成测试和端到端测试。 ## 1. 代码组织和结构： - **目录结构：** - `components/`：可重用的 Vue 组件。 - `composables/`：可重用的组合式函数。 - `layouts/`：应用程序布局。 - `middleware/`：路由中间件。 - `pages/`：应用程序页面（路由定义）。 - `plugins/`：Nuxt.js 插件。 - `server/`：API 路由和服务端逻辑。 - `static/`：静态资源（例如，图片、字体）。 - `store/`：Pinia stores（可选，但推荐）。 - `utils/`：工具函数。 - **文件命名约定：** - 组件：`PascalCase.vue`（例如，`MyComponent.vue`） - 组合式函数：`usePascalCase.js` 或 `usePascalCase.ts`（例如，`useCounter.js`） - 布局：`kebab-case.vue`（例如，`default.vue` 或 `custom-layout.vue`） - 页面：`kebab-case.vue`（例如，`index.vue`、`about.vue`、`product-details.vue`） - 插件：`kebab-case.js` 或 `kebab-case.ts`（例如，`analytics.js`） - Stores：`kebab-case.js` 或 `kebab-case.ts`（例如，`user-store.js`） - 工具函数：`camelCase.js` 或 `camelCase.ts`（例如，`formatDate.js`） - **模块组织：** - 将相关功能分组到单独的模块中。 - 在 `nuxt.config.js` 或 `nuxt.config.ts` 中使用 `@nuxt/modules` 数组注册模块。 - 创建自定义模块来封装复杂逻辑。 - **组件架构：** - 优先使用组合而非继承。 - 对简单的 UI 元素使用函数式组件。 - 设计组件时考虑可重用性和可测试性。 - 考虑使用插槽进行灵活的组件组合。 - **代码分割：** - 利用动态导入进行基于路由的代码分割。 - 使用 `import()` 将大组件分割成更小的块。 - 使用 Webpack Bundle Analyzer 等工具分析包大小。 ## 2. 常见模式和反模式： - **设计模式：** - **组合式 API：** 使用组合式 API 来组织组件逻辑。 - **Store 模式 (Pinia)：** 使用 Pinia 实现集中式状态管理系统。 - **中间件模式：** 使用中间件进行身份验证、授权和数据验证。 - **插件模式：** 为全局功能和第三方库集成创建插件。 - **推荐方法：** - **API 通信：** 在组件内使用 `useFetch` 或 `useAsyncData` 组合式函数进行 API 调用。 - **表单处理：** 利用 Vue 的内置表单处理功能与 `v-model` 和像 VeeValidate 这样的验证库。 - **身份验证：** 使用 `@nuxt/auth` 库或自定义解决方案实现安全的身份验证流程。 - **授权：** 使用中间件和 Pinia stores 实现基于角色的访问控制 (RBAC)。 - **反模式：** - **直接修改 props：** 避免从子组件直接修改父组件数据。请使用 `emit` 代替。 - **过度使用全局状态：** 将全局状态的使用限制在必要的应用程序数据上。对本地数据考虑使用组件级状态。 - **忽略错误处理：** 始终处理 API 调用和其他异步操作中的潜在错误。 - **编写过于复杂的组件：** 将大组件分解为更小、更易管理的部分。 - **状态管理最佳实践：** - **单一数据源：** 在 Pinia stores 中为应用程序状态维护单一、一致的数据源。 - **不可变性：** 将状态视为不可变的。使用函数来更新 store 而不是直接操作数据。 - **清晰的命名约定：** 为 store 模块、actions 和 mutations 使用描述性名称。 - **模块化：** 根据功能或特性将 stores 分成模块。 - **错误处理模式：** - **集中式错误处理：** 实现全局错误处理器来捕获未处理的异常。 - **错误边界：** 使用错误边界来隔离组件故障并防止级联错误。 - **用户友好的错误消息：** 为用户提供清晰和有用的错误消息。 ## 3. 性能考虑： - **优化技术：** - **懒加载：** 为图片、组件和路由实现懒加载。 - **代码分割：** 将应用程序分割成更小的块以获得更快的初始加载时间。 - **Tree Shaking：** 在构建过程中删除未使用的代码。 - **缓存：** 缓存 API 响应和静态资源以减少服务器负载。 - **图片优化：** 使用 `nuxt/image` 等工具优化图片。使用适当的图片格式（WebP）。将图片大小调整为适当大小。考虑使用 CDN 进行图片交付。 - **内存管理：** - **避免内存泄漏：** 在组件卸载时清理事件监听器和定时器。 - **使用弱引用：** 在可能的情况下对 DOM 元素使用弱引用。 - **最小化对象创建：** 避免创建不必要的对象和数组。 - **渲染优化：** - **虚拟化：** 对大列表使用虚拟化以提高渲染性能。 - **记忆化：** 记忆化昂贵的计算以避免冗余计算。有效使用 `computed` 属性以避免不必要的重新渲染。 - **防抖和节流：** 对事件处理器使用防抖和节流以减少函数调用次数。 - **包大小优化：** - **分析包大小：** 使用 Webpack Bundle Analyzer 识别大依赖项。 - **删除未使用的依赖项：** 删除未使用的依赖项以减少包大小。 - **使用更小的替代方案：** 考虑使用更小的替代方案来替代大型库。 - **优化依赖项：** 检查依赖项并确保您使用的是最高效的版本。 - **懒加载策略：** - **基于路由的懒加载：** 仅在访问相应路由时加载组件。 - **基于组件的懒加载：** 仅在组件在视口中可见时加载组件。 ## 4. 安全最佳实践： - **常见漏洞：** - **跨站脚本攻击 (XSS)：** 通过正确清理用户输入和使用 Vue 的内置 HTML 转义来防止 XSS 攻击。 - **跨站请求伪造 (CSRF)：** 通过实现 CSRF 令牌来防止 CSRF 攻击。 - **SQL 注入：** 避免原始 SQL 查询。使用 ORM（对象关系映射器）来防止 SQL 注入。 - **身份验证和授权缺陷：** 实现安全的身份验证和授权机制。 - **不安全的直接对象引用 (IDOR)：** 实现适当的访问控制以防止对资源的未授权访问。 - **输入验证：** - **服务端验证：** 始终在服务端验证用户输入。 - **客户端验证：** 提供客户端验证以获得更好的用户体验（但不要依赖它作为验证的唯一来源）。 - **清理输入：** 清理用户输入以删除潜在的有害字符。 - **身份验证和授权模式：** - **JWT（JSON Web Tokens）：** 使用 JWT 进行身份验证和授权。 - **OAuth 2.0：** 为第三方身份验证实现 OAuth 2.0。 - **基于角色的访问控制 (RBAC)：** 实现 RBAC 来根据用户角色控制对资源的访问。 - **数据保护策略：** - **加密：** 对静态和传输中的敏感数据进行加密。 - **散列：** 使用强散列算法对密码和其他敏感数据进行散列。 - **数据屏蔽：** 在日志和其他非生产环境中屏蔽敏感数据。 - **安全的 API 通信：** - **HTTPS：** 始终使用 HTTPS 进行 API 通信。 - **API 速率限制：** 实现 API 速率限制以防止滥用。 - **身份验证和授权：** 对所有 API 端点要求身份验证和授权。 ## 5. 测试方法： - **单元测试：** - **测试单个组件：** 孤立地测试单个组件。 - **模拟依赖项：** 模拟外部依赖项以在测试期间隔离组件。 - **验证组件行为：** 验证组件正确渲染并按预期行为。 - **集成测试：** - **测试组件交互：** 测试组件之间的交互。 - **测试数据流：** 测试组件和 stores 之间的数据流。 - **测试 API 集成：** 测试与外部 API 的集成。 - **端到端测试：** - **模拟用户交互：** 模拟用户交互以测试应用程序的功能。 - **测试整个应用程序流程：** 从头到尾测试整个应用程序流程。 - **使用浏览器自动化工具：** 使用 Cypress 或 Playwright 等浏览器自动化工具。 - **测试组织：** - **按功能组织测试：** 按功能或特性组织测试。 - **使用描述性测试名称：** 使用描述性测试名称来清楚地说明每个测试正在测试什么。 - **保持测试隔离：** 保持测试彼此隔离以避免干扰。 - **模拟和存根：** - **使用模拟对象：** 使用模拟对象在测试期间替换外部依赖项。 - **使用存根：** 使用存根用简化版本替换复杂函数。 - **避免过度模拟：** 避免模拟太多代码，因为这会使测试效果降低。 ## 6. 常见陷阱和注意事项： - **常见错误：** - **错误的 `this` 上下文：** 注意 Vue 组件中的 `this` 上下文，使用箭头函数或 `bind` 来维护正确的上下文。 - **异步数据处理：** 使用 `async/await` 或 Promises 正确处理异步数据加载。 - **忘记取消订阅：** 在组件卸载时取消订阅事件监听器和定时器以防止内存泄漏。 - **过度使用 `forceUpdate`：** 除非绝对必要，否则避免使用 `forceUpdate`，因为它会对性能产生负面影响。 - **边缘情况：** - **服务端渲染 (SSR)：** 了解客户端和服务端渲染之间的差异。 - **浏览器兼容性：** 在不同浏览器中测试应用程序以确保兼容性。 - **可访问性：** 在设计和开发应用程序时考虑可访问性。 - **版本特定问题：** - **Nuxt 2 vs Nuxt 3：** 了解 Nuxt 2 和 Nuxt 3 之间的差异。 - **Vue 2 vs Vue 3：** 了解 Vue 2 和 Vue 3 之间的差异。 - **依赖项更新：** 仔细检查依赖项更新是否存在潜在的破坏性更改。 - **兼容性问题：** - **浏览器支持：** 确保与目标浏览器兼容。 - **设备兼容性：** 在不同设备上测试应用程序。 - **操作系统兼容性：** 确保与目标操作系统兼容。 - **调试策略：** - **使用浏览器开发者工具：** 使用浏览器开发者工具检查应用程序的状态和网络活动。 - **使用 Vue Devtools：** 使用 Vue Devtools 检查 Vue 组件和数据。 - **使用日志记录：** 使用日志记录来跟踪应用程序的行为。 ## 7. 工具和环境： - **推荐的开发工具：** - **VS Code：** Visual Studio Code 是一个流行的代码编辑器，具有出色的 Vue.js 支持。 - **Vue Devtools：** Vue Devtools 是一个浏览器扩展，为 Vue.js 应用程序提供调试工具。 - **ESLint：** ESLint 是一个强制执行编码标准的代码检查器。 - **Prettier：** Prettier 是一个自动格式化代码的代码格式化器。 - **构建配置：** - **`nuxt.config.js` 或 `nuxt.config.ts`：** 在 `nuxt.config.js` 或 `nuxt.config.ts` 中配置应用程序的构建设置。 - **Webpack：** Nuxt 使用 Webpack 来打包应用程序。 - **Vite：** Nuxt 3 默认使用 Vite 来打包应用程序，提供更快的构建和开发时间。 - **代码检查和格式化：** - **ESLint：** 使用 ESLint 强制执行编码标准。 - **Prettier：** 使用 Prettier 自动格式化代码。 - **Husky：** 使用 Husky 在提交前运行代码检查器和格式化器。 - **部署最佳实践：** - **服务端渲染 (SSR)：** 将应用程序部署到支持 SSR 的服务器。 - **静态站点生成 (SSG)：** 为内容丰富的应用程序生成静态站点。 - **CDN：** 使用 CDN 交付静态资源。 - **CI/CD 集成：** - **持续集成 (CI)：** 使用 Jenkins、GitLab CI 或 GitHub Actions 等 CI 工具自动化构建和测试过程。 - **持续部署 (CD)：** 使用 CD 工具自动化部署过程。 通过遵循这些最佳实践，您可以构建强健、可维护且可扩展的 Nuxt.js 应用程序。