--- title: "贡献" description: "Nuxt 是一个社区项目 —— 因此我们欢迎各种形式的贡献！❤️" canonical_url: "https://nuxt.zhcndoc.com/docs/4.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/4.x/guide/modules/ecosystem)，可将模块迁移到 `nuxt-modules`。这些模块虽然由各自的维护者维护，但并不依赖某一个人。 - [unjs/](https://github.com/unjs) - 其中的许多库都应用于 Nuxt 生态系统。它们被设计为通用库，不依赖任何框架或运行环境。我们欢迎其他框架和项目使用这些库并为其做出贡献。 ## 如何贡献 ### 分类问题并参与讨论 查看你想要帮助的项目的 issues 和 discussions。例如，这是 Nuxt 的[issues 面板](https://github.com/nuxt/nuxt/issues)和[discussions](https://github.com/nuxt/nuxt/discussions)。帮助其他用户、分享变通方案、创建可复现的示例，或者稍微研究一个 bug 并分享你的发现，都会产生巨大的影响。 ### 创建 Issue 感谢你抽时间创建 Issue！❤️ - **报告 bug**：查看[我们的指南](https://nuxt.zhcndoc.com/docs/4.x/community/reporting-bugs)，了解提交 issue 前需要做些什么。 - **功能请求**：请先检查是否已有现成的 issue 或 discussion 涵盖了你想要的功能范围。如果该功能属于 Nuxt 生态系统的其他部分（例如某个模块），请先考虑在对应仓库提交功能请求。如果你设想的功能比较通用或 API 尚不明确，建议先在 **Ideas** 区域开启一个 discussion 与社区讨论。 在响应 Issues 时，我们会尽量遵循我们的[内部问题决策流程图](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 中实现该功能。 对于拼写或错别字修复，建议将多个拼写修复合并为一个 Pull Request，以保持提交历史的整洁。 对于 Nuxt 本身的较大改动，我们建议你先[创建一个 Nuxt 模块](https://nuxt.zhcndoc.com/docs/4.x/community/contribution#create-a-module)，并在其中实现该功能。这样可以快速验证概念。然后你可以通过 discussion 的形式[创建一个 RFC](https://nuxt.zhcndoc.com/docs/4.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 如果你不知道如何发起 Pull Request，建议阅读[该指南](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/4.x/community/contribution#commit-conventions)。 如果你的 PR 修复或解决了现有 issue，请在 PR 描述中提及它们。 一个 PR 中有多个提交是可以接受的；你不需要为你的变更 rebase 或强制推送，因为我们在合并时会使用 `Squash and Merge` 将这些提交压缩为一个提交。 我们不会添加任何提交钩子以便快速提交。但是在创建 PR 之前，请确保任何 lint/test 脚本都是通过的。 通常，请确保 PR 中没有无关的更改。例如，如果你的编辑器在你编辑的文件的其他地方更改了空格或格式，请还原这些更改，以便更清楚地看出你的 PR 做了哪些更改。并请避免在单个 PR 中包含多个不相关的功能或修复。如果可以拆分，最好分别提交多个 PR 以便单独审查和合并。一般来说，PR 应该只做“一件事”。 #### 提交 PR 后 创建 PR 后，我们会尽力尽快进行审查。 如果我们把 PR 指派给某位维护者，表示该人会特别负责审查并按需实现变更。 如果我们在 PR 上请求了更改，请别被红色文字吓到！这并不意味着我们认为这是个糟糕的 PR —— 这只是方便快速查看一系列 PR 状态的方式之一。 如果我们将 PR 标记为“pending”，这意味着在审查该 PR 时我们可能还有其他任务要做 —— 这是内部的备忘，并不一定反映该 PR 是否是个好想法或有问题。我们会尽力通过评论解释 pending 状态的原因。 在响应和审阅 Pull Request 时，我们也会尽量遵循[我们的 PR 决策流程图](https://mermaid.live/view#pako:eNp9VE1v2kAQ_SsjXzBSEqlALlaUisSh0ACK2l4qcVm8Y9hi7672Iwly-O-ZtYPt5FAOCHbee_PmzdpVlCmOURLlhXrJ9sw4-JNuJNBnWs1UQafIQVjrERyWumAOv58-AJeXt29_0b7BXbWwwL0uRPa1vlZvcB_fF8oiMMmM2QM4BXkt3UoON7Lh3LWaDz2SVkK6QGt7DHvw0CKt5sxCKaQoWQEGtVHcZ04oGdw04LTVngW_LHOeFcURGGz97mw6PSv-iJdsi0UCA4nI7SfNwc3W3JZit3eQ1SZFDlKB15yswQ2MgbOjbYeatY3n8bcr-IWlekYYaJRcyB04I9gOB1CEfkF5dAVTzmFAtnqn4-bUYAiMMmHZgWhNPRhgus5mW2BATxq0NkIZ4Y4NbNjzE2ZchBzcHmGLe_ZMSKCcyRXyLrVFa_5n_PBK2xKy3kk9eOjULUdltk6C8kI-7NFDr8f4EVGDoqlp-wa4sJm3ltIMIuZ_mTQXJyTSkQZtunPqsKxShV9GKdkBYe1fHXjpbcjlvONlO9Kqx_M7YHmOmav_luxfE5zKwVs09hM5DLSupgYDlr5flDkwo7ykixKG-xDsUly1LZ-uY32dgDc7lG7YqwbNp0msJwmIUivjWFtfd-xRrEcJ7Omydz37qFplHOtxEp4GskI2qB5dRCWakglOz3oV8JuITJa4iRL6yZk5bKKNPBGOead-H2UWJc54vIiaW53SPgwrz4fIhVNm1bw76lfI6R2_MW21)。 ### AI 辅助的贡献 我们欢迎在为 Nuxt 做贡献时审慎地使用 AI 工具，同时要求所有贡献者遵循[两个核心原则](https://roe.dev/blog/using-ai-in-open-source)。 #### 不要让 LLM 代你发声 - 所有评论、issue 和 PR 描述应以你自己的语言撰写 - 我们重视清晰、有人情味的沟通，而非完美的语法或拼写 - 避免直接复制粘贴 AI 生成但并不反映你自身理解的摘要 #### 不要让 LLM 替你思考 - 可以自由使用 AI 工具来生成代码或探索想法 - 仅提交你完全理解并能解释的贡献 - 贡献应当反映你自己的推理和问题解决过程 我们的目标是确保质量并保持与真实人物协作和沟通的乐趣。如果你有改进 Nuxt 社区 AI 使用政策的想法，我们非常愿意听取！❤️ ### 创建模块 如果你用 Nuxt 构建了很棒的东西，不妨[将它提取为一个模块](https://nuxt.zhcndoc.com/docs/4.x/guide/modules)，与其他人分享？我们已经有[许多优秀的模块](https://nuxt.zhcndoc.com/modules)，但还有更多空间。 如果你在构建过程中需要帮助，欢迎[联系我们](https://nuxt.zhcndoc.com/docs/4.x/community/getting-help)。 ### 制定 RFC 我们强烈建议先[创建一个模块](https://nuxt.zhcndoc.com/docs/4.x/community/contribution#create-a-module)，以测试大型新功能并获得社区采用。 如果你已经这么做了，或者创建新模块不合适，请先创建一个新的 discussion。确保尽可能清晰地说明你的思路。为新的 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/4.x/guide/modules)。 #### 使用核心 `unjs/` 库 我们推荐在生态系统中使用下列库： - [pathe](https://github.com/unjs/pathe) - 通用路径工具（替代 Node 的 `path`） - [ufo](https://github.com/unjs/ufo) - URL 解析和拼接工具 - [obuild](https://github.com/unjs/obuild) - 基于 rollup 的构建系统 - ... 还有更多，请查看 [unjs/](https://github.com/unjs) 组织！ #### 使用 ESM 语法并默认设置为 `type: module` Nuxt 生态系统中的大多数项目都可以直接使用 ESM。一般来说，我们建议避免使用 CJS 专用代码，例如 `__dirname` 和 `require` 语句。你可以[进一步了解 ESM](https://nuxt.zhcndoc.com/docs/4.x/guide/concepts/esm)。 #### 什么是 Corepack [Corepack](https://github.com/nodejs/corepack) 确保在运行对应命令时使用正确版本的包管理器。项目的 `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) 来做 lint 和格式化。 ##### 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/4.x/community/contribution#use-eslint)了解 IDE 设置。 如果你的编辑器中安装了 Prettier，建议在参与项目工作时将其禁用以避免冲突。 #### 包管理器 我们推荐在模块、库和应用中使用 `pnpm` 作为包管理器。 重要的是启用 Corepack，以确保你使用的包管理器版本与项目一致。Corepack 已内置于较新的 Node 版本中，以实现无缝的包管理器集成。 启用命令为： ```bash [Terminal] corepack enable ``` 在你的计算机上安装 Node.js 后，你只需要执行一次该操作。 ## 文档风格指南 文档是 Nuxt 的重要组成部分。我们力求成为一个直观的框架 —— 而这在很大程度上取决于开发者体验以及文档在整个生态系统中的完备程度。👌 下面是一些可能有助于改进文档的建议： ### 语言 - 使用**美式英语**拼写（*behavior* 而不是 *behaviour*，*customize* 而不是 *customise*）。 - 使用工具和项目的官方大小写来书写，即使 npm 包名是小写的也是如此（例如，*PostCSS* 而不是 *postcss*，*Vite* 而不是 *vite*，*ESLint* 而不是 *eslint*）。只有在指代包本身时，才在反引号中使用小写的 npm 包名，例如在安装说明中。 ::caution{icon="i-lucide-circle-x"} Nuxt 原生支持 postcss。 :: ::tip{icon="i-lucide-circle-check"} Nuxt 原生支持 PostCSS。你不需要手动安装 `postcss`。 :: ::note 当你运行 `pnpm lint:docs` 时，常见工具名称的大小写会由 [case police](https://github.com/antfu/case-police) 自动检查。 :: ### 标题 - 标题应遵循 Chicago title case 进行首字母大写。简而言之：首个单词、最后一个单词以及所有主要单词（名词、动词、形容词、副词、代词）首字母大写；冠词、并列连词和介词无论长度一律小写（例如 a、and、or、with、from 和 to）。如有疑问，[capitalizemytitle.com](https://capitalizemytitle.com/style/Chicago) 可以提供帮助。 ::caution{icon="i-lucide-circle-x"} 如何为文档做出贡献 :: ::tip{icon="i-lucide-circle-check"} 如何为文档做出贡献 :: - 标题中的代码保持其原始大小写，并且不计入首字母大写规则（例如，*在组件中使用 `useFetch`*）。 ### 行内代码 将以下内容用反引号包裹，以便渲染为行内代码： - 文件名和路径：`nuxt.config.ts`、`server/api/` - npm 包名：`@nuxt/kit`、`postcss` - 配置键、选项和值：`ssr: false`、`css` 选项 - 代码标识符，如函数、组合式函数、组件、变量和类型：`useFetch`、``、`defineNuxtConfig` - 终端命令：`npx nuxt init` 不要将工具、项目或一般概念的名称放在反引号中（提到工具时应使用 *Vite*，而不是 `vite`）。 ### 代码示例 - 为代码块添加文件名，这样读者就知道代码属于哪里。如果代码不属于某个特定文件（例如 shell 命令），请使用描述性标签，如 `[Terminal]`。 ~~~markdown ```ts [nuxt.config.ts] export default defineNuxtConfig({ ssr: false, }) ``` ~~~ - 让示例能够直接复制粘贴。包含必要的 import，并避免在读者会复制到项目中的代码中间使用诸如 `...` 之类的占位符。读者应该能够将示例复制到项目中，并在只做少量修改的情况下正常运行。 ### 链接 - 链接到其他文档页面时，请使用不带域名或版本号的相对路径：`/docs/getting-started/installation`，而不是 `/docs/4.x/getting-started/installation` 或 `https://nuxt.com/docs/4.x/getting-started/installation`。[nuxt.com](http://nuxt.com) 会插入构建该页面所用分支的版本号，因此同一个链接在每个版本中都能正确解析，文档更改也可以原样 cherry-pick 到不同分支。 - 只有在明确指向\_另一个\_版本的文档时，才写版本号（例如路线图中的发布表）。这种情况下请使用完整 URL：`https://nuxt.com/docs/3.x/getting-started/introduction`，以便审阅者清楚地了解你的意图。 - 链接到外部资源时，请链接到最终 URL，而不是会重定向的 URL。你可以使用以下命令检查： ```bash [Terminal] curl -sILo /dev/null -w '%{http_code} %{url_effective}\n' https://example.com/some-page ``` 该命令会跟随所有重定向链并输出最终状态和 URL。状态码为 `200` 且 URL 与请求的一致，说明链接没有问题。如果最终 URL 不同，就链接到那个最终 URL。 ### 语气 我们的目标是友好而专业的语气。直接对读者使用“你”，表达简洁，并假设读者怀有善意：读者来自不同背景，经验水平也各不相同，因此应避免使用会让人觉得被居高临下对待的措辞。保持温暖是可以的——文档可以有个性——但清晰始终是第一位的。 ### 写作风格 - 尽量避免使用主观词语，如 *简单地*、*只是*、*显然* 等。 请记住你的读者可能具有不同的背景和经验。因此，这些词无法传达实际含义，反而可能造成误导。 ::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 会抛出一个错误。 :: - 在编写 API 页面文档时，包括 composables、utilities 和 components，请使用一致的章节名称和顺序。仅包含适用的章节： 1. **Usage**：说明如何使用该 API，并涵盖常见用例。 2. **Type**：提供相关的 TypeScript 声明。 3. **Parameters**：描述每个输入，包括其类型、默认值和可用选项。 4. **Return Values**：描述返回值及其类型。 5. **Example**：展示一个实际示例。 请使用这些确切的章节名称。例如，使用 `Parameters` 而不是 `Params`，使用 `Example` 而不是 `Examples`。 - 在编写 API 页面（composables、utils、components）文档时，请为功能或工具首次引入时添加**最小 Nuxt 版本**，以便读者知道他们需要哪个版本。 分为两个层级： - **全局（整页）：** 在 frontmatter 中添加 `minimalVersion: "3.9"`（不带 "v" 前缀）。文档布局会根据此字段自动渲染版本徽章，显示为 `vX.Y`（例如 `v3.9`、`v3.15`）。 - **局部（特定选项或功能）：** 在选项或章节旁添加一个小徽章：`:badge[v3.8]{color="info" size="xs" class="align-middle"}`（例如用于 useFetch 中的 `getCachedData`，或用于 callOnce 中的 `navigation` 模式）。 要查找版本，请查看源代码 JSDoc 中的 `@since`、[发布说明](https://github.com/nuxt/nuxt/releases) 或 [Nuxt 博客](https://nuxt.com/blog)。 ::read-more{to="https://nuxt.zhcndoc.com/docs/4.x/community/framework-contribution#documentation-guide"} 了解如何为文档做出贡献。 :: ## Sitemap See the full [sitemap](https://nuxt.zhcndoc.com/sitemap.md) for all pages.