贡献

Nuxt 是一个社区项目——因此我们欢迎各种形式的贡献！❤️

你可以通过多种不同的方式为 Nuxt 生态系统做出贡献。

生态系统

Nuxt 生态系统包含许多不同的项目和组织：

  • nuxt/ - Nuxt 框架本身的核心仓库。nuxt/nuxt 包含 Nuxt 框架的版本 2 和 3。
  • nuxt-modules/ - 社区贡献和维护的模块与库。这里有一个模块迁移流程到 nuxt-modules。虽然这些模块由各自的维护者负责，但它们不依赖单一人员。
  • unjs/ - 许多库在 Nuxt 生态系统中被广泛使用。它们设计为通用库，独立于框架和环境。我们欢迎其他框架和项目的贡献与使用。

如何贡献

分类问题并参与讨论

查看你想帮助的项目的问题（issues）和讨论（discussions）。例如，以下是 Nuxt 的问题列表和讨论区。帮助其他用户、分享解决方案、创建复现示例，或者稍微研究一下 bug 并分享你的发现，都会带来巨大的影响。

创建问题（Issues）

感谢你花时间创建问题！❤️

  • 报告 Bug：请查看我们的指南，了解在提 issue 前需要做的一些准备工作。
  • 功能请求：请确认是否已有相关 issue 或讨论涵盖你想要的功能范围。如果功能属于 Nuxt 生态系统的其他部分（如某个模块），请优先在那里提出功能请求。如果你的功能需求较为通用或 API 不够明确，建议先在 Ideas 区域开启讨论，与社区沟通交流。

我们会尽力依据我们的内部问题决策流程图来响应问题。

提交 Pull Request

我们始终欢迎 Pull Requests！❤️

开始前的准备

在修复 Bug 之前，建议先确认是否已有相关 issue，因为可能是文档错误或存在有用的上下文信息。

如果你在开发新功能，请先开启一个功能请求 issue，与维护者讨论该功能是否被需要以及设计细节。这可以节省维护者和贡献者双方的时间，并帮助功能更快发布。该 issue 必须由框架团队成员确认，才可开始在 PR 中实现功能。

对拼写错误的修正建议集中在一个 PR 中提交，以保持提交历史整洁。

对 Nuxt 本身进行较大改动时，建议先创建一个 Nuxt 模块实现功能原型，再以讨论形式创建 RFC。用户采用并反馈后，功能可以完善并合入 Nuxt 核心或继续作为独立模块。

提交规范

提交信息采用 Conventional Commits 规范，可自动生成变更日志。如果你不熟悉，请务必阅读相关指南。

注意，fix: 和 feat: 用于实际的代码变更（可能影响逻辑）。拼写或文档修改应使用 docs: 或 chore:：

  • fix: typo -> docs: fix typo

如果你在类似 nuxt/nuxt 这种 monorepo 项目中工作，提交信息中请标明主要作用域，如：feat(kit): add 'addMagicStuff' utility。

如何提交 Pull Request

如果你不知道如何发起 PR，推荐阅读官方指南。

发起 PR 时，请确保标题也遵守提交规范。

PR 解决或修复了已有 issues，请务必在 PR 描述中提及它们。

一个 PR 中可以包含多个提交；你无需对提交进行 rebase 或强制推送，我们会使用“Squash and Merge”方式合并成一个提交。

我们不会配置任何提交钩子以支持快速提交，但发起 PR 前，请确保所有 lint 和测试脚本通过。

一般请确保 PR 中不包含与主改动无关的变更。例如编辑器自动调整的空白或格式变动请还原，避免干扰审核。且避免在一个 PR 中包含多项无关功能或修复，最好分开成多个 PR 分别审查合并。原则上，一个 PR 仅做“单一事项”。

发起 PR 后

发起 PR 后，我们会尽快进行审查。

如果我们给 PR 指派了维护者，说明该维护者将特别关注其审查和改动。

如果我们在 PR 上请求改动，请别在意红色文字！这并不代表 PR 不好，而是方便快速查看状态的方式。

如果标记为“pending”，说明可能还有其他任务待完成，是内部提醒，并非反映 PR 是否合理。我们会尽力在评论中说明“pending”原因。

我们会尽力遵照PR 决策流程图审查 PR。

AI 辅助贡献

我们欢迎在贡献 Nuxt 过程中合理使用 AI 工具，但请所有贡献者遵守两个核心原则。

永远不要让语言模型替你发言

  • 所有评论、问题和拉取请求描述都应以你自己的语气书写
  • 我们重视清晰、有人情味的沟通，胜过完美的语法或拼写
  • 避免复制粘贴 AI 生成的摘要，这些摘要未必反映你自己的理解

永远不要让语言模型替你思考

  • 可以自由使用 AI 工具生成代码或探索想法
  • 仅提交你完全理解且能解释的贡献
  • 贡献应体现你自身的推理和解决问题能力

我们的目标是确保质量并保持与真实人沟通协作的乐趣。如果你有改进 Nuxt 社区 AI 使用政策的想法，欢迎告诉我们！❤️

创建模块

如果你用 Nuxt 做了很酷的东西，何不将其抽离成一个模块，方便共享？我们已经有很多优秀模块，但永远欢迎更多。

构建模块时若需帮助，欢迎随时联系我们。

制定 RFC

我们强烈建议先创建模块验证大型新功能并获得社区采用。

如果你已经这么做了，或不适合创建新模块，请先开启新讨论。确保尽可能清晰地阐明你的想法，附上代码示例或新 API 的函数签名，引用相关问题和痛点实例。

如果我们认为应制定 RFC，会将讨论类别切换成 RFC 并广泛征求反馈。

RFC 将经历以下阶段：

  • rfc: active - 正开放征询意见
  • rfc: approved - 被 Nuxt 团队批准
  • rfc: ready to implement - 已创建并分配相应实现 issue
  • rfc: shipped - 已实现
  • rfc: archived - 未批准，但存档备查

生态系统中的规范

以下规范在 nuxt/ 组织内是_必须_遵守的，其他维护者也建议采纳。

模块规范

模块应遵循Nuxt 模块模板规范。详见module 指南。

使用核心 unjs/ 库

推荐使用下面这些贯穿生态系统的库：

  • pathe - 通用路径工具（取代 node 的 path）
  • ufo - URL 解析和合并工具
  • unbuild - 基于 rollup 的构建系统
  • … 更多可查看unjs/ 组织其他仓库！

使用 ESM 语法并默认 type: module

大多数 Nuxt 生态系统都能直接消费 ESM。一般建议避免使用 CJS 特有的代码，如 __dirname 和 require。可阅读更多关于 ESM 的内容这里。

什么是 Corepack

Corepack 能确保你运行命令时使用合适版本的包管理器。项目的 package.json 中可能包含 packageManager 字段。

在配置如下的项目中，Corepack 会安装 pnpm 的 v7.5.0 版本（如果你尚未安装）并使用它执行命令。

package.json
{
  "packageManager": "pnpm@7.5.0"
}

使用 ESLint

我们使用 ESLint 做代码检查和格式化，配合使用@nuxt/eslint。

IDE 设置

推荐使用 VS Code 和 ESLint 扩展。如果愿意，可启用自动修复和格式化保存功能：

settings.json
{
  "editor.codeActionsOnSave": {
    "source.fixAll": "never",
    "source.fixAll.eslint": "explicit"
  }
}

不使用 Prettier

由于 ESLint 已配置代码格式化，无需再使用 Prettier 重复功能。你可以运行 yarn lint --fix，pnpm lint --fix，或 bun run lint --fix 来格式化代码，或参考ESLint 章节进行 IDE 设置。

如果你的编辑器安装了 Prettier，建议在参与本项目时禁用它，以避免冲突。

包管理器

推荐在模块、库和应用中使用 pnpm 作为包管理器。

强烈建议启用 Corepack，确保你使用的包管理器版本与项目一致。Corepack 集成在较新的 Node 版本中，实现无缝的包管理器支持。

启用命令：

Terminal
corepack enable

该操作在电脑安装 Node.js 后只需执行一次。

文档风格指南

文档是 Nuxt 的重要组成部分。我们致力于打造直观易用的框架，其中很大一部分是确保开发者体验和生态系统内的文档都是完美的。👌

以下是一些可助你改进文档的建议：

  • 尽量避免使用 simply、just、obviously 等主观词汇。
    记住读者背景和经验不同，这些词不具实质含义，反而可能造成误解。
    Simply make sure the function returns a promise.
    Make sure the function returns a promise.
  • 优先使用主动语态。
    An error will be thrown by Nuxt.
    Nuxt will throw an error.
了解如何贡献文档。