markdown/blog/1.技术栈/989.Nuxt3 代码规范.md

title, description, date, img, navigation

title	description	date	img	navigation
Nuxt3 代码规范	这是一份提供给AI大模型的Nuxt3框架规范、编程标准，可以有效提高Cursor等大模型对Nuxt.js框架的编写能力。	2025-07-12	https://lijue-me.oss-cn-chengdu.aliyuncs.com/20250624125918171.png	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 应用程序。