--- title: "贡献" description: "Nuxt 是一个社区项目——因此我们欢迎各种形式的贡献！❤️" canonical_url: "https://nuxt.zhcndoc.com/docs/3.x/community/contribution" --- # 贡献 > Nuxt 是一个社区项目——因此我们欢迎各种形式的贡献！❤️ 你可以通过多种不同的方式为 Nuxt 生态系统做出贡献。 ## 生态系统 Nuxt 生态系统包含许多不同的项目和组织： - [nuxt/](https://github.com/nuxt) - Nuxt 框架本身的核心仓库。[**nuxt/nuxt**](https://github.com/nuxt/nuxt) 包含 Nuxt 框架（版本 2 和 3）。 - [nuxt-modules/](https://github.com/nuxt-modules) - 由社区贡献和维护的模块与库。你可以按照[迁移模块的流程](https://nuxt.zhcndoc.com/docs/3.x/guide/modules/ecosystem)将模块迁移到 `nuxt-modules`。虽然这些模块各自有维护者，但它们并不依赖某一个人。 - [unjs/](https://github.com/unjs) - 其中许多库都应用于 Nuxt 生态系统。这些库旨在成为通用库，不依赖任何框架或环境。我们欢迎其他框架和项目做出贡献并使用这些库。 ## 如何贡献 ### 分类问题并参与讨论 查看你想帮助的项目的问题（issues）和讨论（discussions）。例如，以下是 Nuxt 的[问题列表](https://github.com/nuxt/nuxt/issues)和[讨论区](https://github.com/nuxt/nuxt/discussions)。帮助其他用户、分享解决方案、创建复现示例，或者稍微研究一下 bug 并分享你的发现，都会带来巨大的影响。 ### 创建问题（Issues） 感谢你花时间创建问题！❤️ - **报告 bug**：查看[我们的指南](https://nuxt.zhcndoc.com/docs/3.x/community/reporting-bugs)，了解在创建问题之前需要做些什么。 - **功能请求**：请确认是否已有相关 issue 或讨论涵盖你想要的功能范围。如果功能属于 Nuxt 生态系统的其他部分（如某个模块），请优先在那里提出功能请求。如果你的功能需求较为通用或 API 不够明确，建议先在 **Ideas** 区域开启讨论，与社区沟通交流。 我们会尽力依据我们的[内部问题决策流程图](https://mermaid.live/view#pako:eNqFlE1v2zAMhv8K4UuToslhx2Bo0TZt12Edhm7YMCAXWqJtorLk6qOpkfS_j7KdfpyWQ-BQr8mHL6nsCuU0FauiMm6rGvQRfq03FuRzvvvTYIQHthpcBT_ugQNwPHuZjheLxf4i1VDx8x4udrf5EBCOQvSsYg4ffS79KS9pmX9QALTgyid2KYB7Ih-4bmKWbDk2YB0E1gRUVaRi-FDmmjAmT3u4nB3DmoNKIUA1BsGSohA49jnVMQhHbDh_EZQUImyxh-gAtfaiG-KWSJ-N8nt6YtpCdgEeE5rXPOdav5YwWJIJU7zrvNADV9C7JBIyIC07Wxupkx3LFQ5vCkguRno5f9fP2qnUko0Y2dk9rGdvHAa9IIhVGlCp5FFNPN-ce4DKeXBd53xMliOLp9IZtyORQVsnrGm-WJzejtUu5fFqdr5FGQ3bLslYvGthjZbJTLpReZG5_lLYw7XQ_CbPVT92ws9gnEJj-v84dk-PiaXnmF1XGAaPsOsMKywNvYmG80ZohV8k4wDR9_N3KN_dHm5mh1lnkM5FsYzRfNiTvJoT5gnQsl6uxjqXLhkNQ9syHJ0UZZ8ERUIlNShr6N8gZDEliR-ow7QZa0fhY4LoHLRo-8N7ZxPwjRj5ZZYXpvOSNs9v3Jjs8NXB4ets92xan3zydXZHvj64lKMayh4-gZC1bjASW2ipLeWuzIuToiXfImu5rbucclMIc0ubYiWPGv3DptjYF9Fhiu5nb1Wxij7RSZE6jZHWjLXHtlhVaIJESXN0_m68_sO_wMs_oO9gyg)来响应问题。 ### 提交 Pull Request 我们始终欢迎 Pull Requests！❤️ #### 开始前的准备 在修复 Bug 之前，建议先确认**是否已有相关 issue**，因为可能是文档错误或存在有用的上下文信息。 如果你在开发新功能，请先**开启一个功能请求 issue**，与维护者讨论该功能是否被需要以及设计细节。这可以节省维护者和贡献者双方的时间，并帮助功能更快发布。该 issue 必须由框架团队成员**确认**，才可开始在 PR 中实现功能。 对拼写错误的修正建议集中在一个 PR 中提交，以保持提交历史整洁。 对于 Nuxt 本身的较大改动，我们建议你先[创建一个 Nuxt 模块](https://nuxt.zhcndoc.com/docs/3.x/community/contribution#create-a-module)，并在其中实现该功能。这样可以快速验证概念。然后，你可以通过讨论的形式[创建 RFC](https://nuxt.zhcndoc.com/docs/3.x/community/contribution#make-an-rfc)。随着用户开始采用该功能并提供反馈，你可以进一步完善它，之后将其添加到 Nuxt 核心中，或继续作为独立模块维护。 #### 提交规范 提交信息采用 [Conventional Commits](https://www.conventionalcommits.org) 规范，[可自动生成变更日志](https://github.com/unjs/changelogen)。如果你不熟悉，请务必阅读相关指南。 注意，`fix:` 和 `feat:` 用于**实际的代码变更**（可能影响逻辑）。拼写或文档修改应使用 `docs:` 或 `chore:`： - ~~`fix: typo`~~ -> `docs: fix typo` 如果你在类似 `nuxt/nuxt` 这种 monorepo 项目中工作，提交信息中请标明主要作用域，如：`feat(kit): add 'addMagicStuff' utility`。 #### 如何提交 Pull Request 如果你不知道如何发起 PR，推荐阅读[官方指南](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)。 提交 pull request 时，请确保 PR 标题也遵循[提交规范](https://nuxt.zhcndoc.com/docs/3.x/community/contribution#commit-conventions)。 如果 PR 解决或修复了已有 issues，请务必在 PR 描述中提及它们。 一个 PR 中可以包含多个提交；你无需对提交进行 rebase 或强制推送，我们会使用“Squash and Merge”方式合并成一个提交。 我们不会配置任何提交钩子以支持快速提交，但发起 PR 前，请确保所有 lint 和测试脚本通过。 一般请确保 PR 中不包含与主改动无关的变更。例如编辑器自动调整的空白或格式变动请还原，避免干扰审核。且避免在一个 PR 中包含多项无关功能或修复，最好分开成多个 PR 分别审查合并。原则上，一个 PR 仅做“单一事项”。 #### 发起 PR 后 发起 PR 后，我们会尽快进行审查。 如果我们给 PR 指派了维护者，说明该维护者将特别关注其审查和改动。 如果我们在 PR 上请求改动，请别在意红色文字！这并不代表 PR 不好，而是方便快速查看状态的方式。 如果标记为“pending”，说明可能还有其他任务待完成，是内部提醒，并非反映 PR 是否合理。我们会尽力在评论中说明“pending”原因。 我们会尽力遵照[PR 决策流程图](https://mermaid.live/view#pako:eNp9VE1v2kAQ_SsjXzBSEqlALlaUisSh0ACK2l4qcVm8Y9hi7672Iwly-O-ZtYPt5FAOCHbee_PmzdpVlCmOURLlhXrJ9sw4-JNuJNBnWs1UQafIQVjrERyWumAOv58-AJeXt29_0b7BXbWwwL0uRPa1vlZvcB_fF8oiMMmB2QM4BXkt3UoON7Lh3LWaDz2SVkK6QGt7DHvw0CKt5sxCKaQoWQEGtVHcZ04oGdw04LTVngW_LHOeFcURGGz97mw6PSv-iJdsi0UCA4nI7SfNwc3W3JZit3eQ1SZFDlKB15yswQ2MgbOjbYeatY3n8bcr-IWlekYYaJRcyB04I9gOB1CEfkF5dAVTzmFAtnqn4-bUYAiMMmHZgWhNPRhgus5mW2BATxq0NkIZ4Y4NbNjzE2ZchBzcHmGLe_ZMSKCcyRXyLrVFa_5n_PBK2xKy3kk9eOjULUdltk6C8kI-7NFDr8f4EVGDoqlp-wa4sJm3ltIMIuZ_mTQXJyTSkQZtunPqsKxShV9GKdkBYe1fHXjpbcjlvONlO9Kqx_M7YHmOmav_luxfE5zKwVs09hM5DLSupgYDlr5flDkwo7ykixKG-xDsUly1LZ-uY32dgDc7lG7YqwbNp0msJwmIUivjWFtfd-xRrEcJ7Omydz37qFplHOtxEp4GskI2qB5dRCWakglOz3oV8JuITJa4iRL6yZk5bKKNPBGOead-H2UWJc54vIiaW53SPgwrz4fIhVNm1bw76lfI6R2_MW21)审查 PR。 ### AI 辅助贡献 我们欢迎在贡献 Nuxt 过程中合理使用 AI 工具，但请所有贡献者遵守[两个核心原则](https://roe.dev/blog/using-ai-in-open-source)。 #### 永远不要让语言模型替你发言 - 所有评论、问题和拉取请求描述都应以你自己的语气书写 - 我们重视清晰、有人情味的沟通，胜过完美的语法或拼写 - 避免复制粘贴 AI 生成的摘要，这些摘要未必反映你自己的理解 #### 永远不要让语言模型替你思考 - 可以自由使用 AI 工具生成代码或探索想法 - 仅提交你完全理解且能解释的贡献 - 贡献应体现你自身的推理和解决问题能力 我们的目标是确保质量并保持与真实人沟通协作的乐趣。如果你有改进 Nuxt 社区 AI 使用政策的想法，欢迎告诉我们！❤️ ### 创建模块 如果你用 Nuxt 构建了很酷的东西，为什么不[将它提取为一个模块](https://nuxt.zhcndoc.com/docs/3.x/guide/modules)，以便与他人分享呢？我们已经有[许多优秀的模块](https://nuxt.zhcndoc.com/modules)，但总还有更多空间。 如果你在构建过程中需要帮助，欢迎[联系我们](https://nuxt.zhcndoc.com/docs/3.x/community/getting-help)。 ### 制定 RFC 我们强烈建议先[创建一个模块](https://nuxt.zhcndoc.com/docs/3.x/community/contribution#create-a-module)，用来测试大型新功能并获得社区的采用。 如果你已经这么做了，或不适合创建新模块，请先开启新讨论。确保尽可能清晰地阐明你的想法，附上代码示例或新 API 的函数签名，引用相关问题和痛点实例。 如果我们认为应制定 RFC，会将讨论类别切换成 RFC 并广泛征求反馈。 RFC 将经历以下阶段： - `rfc: active` - 正开放征询意见 - `rfc: approved` - 被 Nuxt 团队批准 - `rfc: ready to implement` - 已创建并分配相应实现 issue - `rfc: shipped` - 已实现 - `rfc: archived` - 未批准，但存档备查 ### 生态系统中的规范 以下规范在 `nuxt/` 组织内是\_必须\_遵守的，其他维护者也建议采纳。 #### 模块规范 模块应遵循 [Nuxt 模块模板](https://github.com/nuxt/starter/tree/module)。更多信息请参阅[模块指南](https://nuxt.zhcndoc.com/docs/3.x/guide/modules)。 #### 使用核心 `unjs/` 库 推荐使用下面这些贯穿生态系统的库： - [pathe](https://github.com/unjs/pathe) - 通用路径工具（取代 node 的 `path`） - [ufo](https://github.com/unjs/ufo) - URL 解析和合并工具 - [unbuild](https://github.com/unjs/unbuild) - 基于 rollup 的构建系统 - … 更多可查看[unjs/](https://github.com/unjs) 组织其他仓库！ #### 使用 ESM 语法并默认 `type: module` Nuxt 生态系统中的大多数项目都可以直接使用 ESM。通常，我们建议避免使用特定于 CJS 的代码，例如 `__dirname` 和 `require` 语句。你可以[详细了解 ESM](https://nuxt.zhcndoc.com/docs/3.x/guide/concepts/esm)。 #### 什么是 Corepack [Corepack](https://node.zhcndoc.com/api/corepack.html) 能确保你运行命令时使用合适版本的包管理器。项目的 `package.json` 中可能包含 `packageManager` 字段。 在配置如下的项目中，Corepack 会安装 `pnpm` 的 `v7.5.0` 版本（如果你尚未安装）并使用它执行命令。 ```jsonc [package.json] { "packageManager": "pnpm@7.5.0" } ``` #### 使用 ESLint 我们使用 [ESLint](https://eslint.org) 做代码检查和格式化，配合使用[`@nuxt/eslint`](https://github.com/nuxt/eslint)。 ##### IDE 设置 推荐使用 [VS Code](https://code.visualstudio.com) 和 [ESLint 扩展](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)。如果愿意，可启用自动修复和格式化保存功能： ```json [settings.json] { "editor.codeActionsOnSave": { "source.fixAll": "never", "source.fixAll.eslint": "explicit" } } ``` #### 不使用 Prettier 由于 ESLint 已经配置为格式化代码，因此无需使用 Prettier 重复此功能。要格式化代码，你可以运行 `yarn lint --fix`、`pnpm lint --fix`、`bun run lint --fix` 或 `deno run lint --fix`，也可以参阅[ESLint 部分](https://nuxt.zhcndoc.com/docs/3.x/community/contribution#use-eslint)了解 IDE 设置。 如果你的编辑器安装了 Prettier，建议在参与本项目时禁用它，以避免冲突。 #### 包管理器 推荐在模块、库和应用中使用 `pnpm` 作为包管理器。 强烈建议启用 Corepack，确保你使用的包管理器版本与项目一致。Corepack 集成在较新的 Node 版本中，实现无缝的包管理器支持。 启用命令： ```bash [Terminal] corepack enable ``` 该操作在电脑安装 Node.js 后只需执行一次。 ## 文档风格指南 文档是 Nuxt 的重要组成部分。我们致力于打造直观易用的框架，其中很大一部分是确保开发者体验和生态系统内的文档都是完美的。👌 以下是一些可助你改进文档的建议： - 尽量避免使用 *simply*、*just*、*obviously* 等主观词汇。 记住读者背景和经验不同，这些词不具实质含义，反而可能造成误解。 ::caution{icon="i-lucide-circle-x"} 只需确保该函数返回一个 promise。 :: ::tip{icon="i-lucide-circle-check"} 确保该函数返回一个 [promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)。 :: - 优先使用[主动语态](https://developers.google.com/tech-writing/one/active-voice)。 ::caution{icon="i-lucide-circle-x"} Nuxt 将抛出一个错误。 :: ::tip{icon="i-lucide-circle-check"} Nuxt 会抛出一个错误。 :: ::read-more{to="https://nuxt.zhcndoc.com/docs/3.x/community/framework-contribution#documentation-guide"} 了解如何为文档做出贡献。 :: ## Sitemap See the full [sitemap](https://nuxt.zhcndoc.com/sitemap.md) for all pages.