跳到主要内容
Nuxt 中文
开始使用

贡献

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

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

生态

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

  • nuxt/ - Nuxt 框架本身的核心仓库。nuxt/nuxt 包含 Nuxt 框架（第 2 版和第 3 版）。
  • nuxt-modules/ - 由社区贡献和维护的模块与库。有一个将模块迁移到 nuxt-modules 的流程。虽然这些模块有各自的维护者，但它们并不依赖某一个人。
  • unjs/ - 这些库中许多都被广泛用于整个 Nuxt 生态。它们被设计为通用的库，与框架和环境无关。我们欢迎其他框架和项目进行贡献和使用。

如何贡献

分类问题并在讨论中提供帮助

查看你想帮忙的项目的问题和讨论。例如，这里是 Nuxt 的问题看板和讨论。帮助其他用户、分享变通方案、创建复现，甚至稍微深入排查一个 bug 并分享你的发现，都会带来巨大的不同。

创建问题

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

  • 报告 bug：在打开 issue 之前，请查看我们的指南了解一些需要做的事情。
  • 功能请求：确认没有涵盖你想法范围内功能的现有 issue 或讨论。如果该功能是面向 Nuxt 生态的其他部分（例如某个模块），请考虑先在那里提出功能请求。如果你心中的功能比较通用，或者 API 还不完全清晰，可以考虑在 Ideas 板块中开启一个讨论，先与社区讨论。

在回应问题时，我们会尽力遵循内部问题决策流程图。

发起一个 Pull Request

我们始终欢迎 Pull Request！❤️

开始之前

在修复 bug 之前，我们建议你先确认是否有描述该问题的 issue，因为它可能是文档问题，或者有一些有助于了解的背景信息。

如果你在处理一个功能，我们要求你先开启一个功能请求 issue，与维护者讨论该功能是否必要——以及这些功能的设计。这有助于节省维护者和贡献者的时间，让功能能够更快地发布。在通过 Pull Request 构建功能之前，该 issue 应得到确认。

对于错别字修复，建议将多个错别字修复合并到一个 Pull Request 中，以保持更干净的提交历史。

对于 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

如果你不知道如何发送 Pull Request，我们建议阅读该指南。

发送 Pull Request 时，请确保 PR 的标题也遵循提交约定。

如果你的 PR 修复或解决了现有问题，请确保在 PR 描述中提及它们。

在一个 PR 中包含多个提交是可以的；你不需要为你的更改做 rebase 或 force push，因为我们会在合并时使用 Squash and Merge 将提交压缩为一个。

我们没有添加任何提交钩子，以便快速提交。但在你发起 Pull Request 之前，你应该确保任何 lint/测试脚本都能通过。

一般而言，也请确保 PR 中没有_不相关_的更改。例如，如果你的编辑器对你编辑的文件的其他地方做了任何空白或格式上的更改，请还原这些更改，以便更清楚地看出你的 PR 改了什么。并且请避免在单个 PR 中包含多个不相关的功能或修复。如果可以分开，最好有多个 PR 分别审查和合并。一般来说，一个 PR 应该_只做一件事_。

发起 Pull Request 之后

一旦你发起了 Pull Request，我们会尽力及时审查它。

如果我们把它分配给某位维护者，意味着这个人会特别用心地审查它，并实施任何所需的更改。

如果我们在 PR 上请求更改，请忽略那些红色文字！这并不意味着我们认为这是个糟糕的 PR——它只是一种能一眼看出一组 Pull Request 状态的方式。

如果我们把一个 PR 标记为“pending”（待定），意味着我们在审查该 PR 时可能还有另一个任务要完成——这是一个内部的自我提醒，并不一定是关于该 PR 是否是个好主意的反映。我们会尽力通过评论解释处于待定状态的原因。

在回应和审查 Pull Request 时，我们会尽力遵循我们的 PR 决策流程图。

AI 辅助贡献

我们欢迎在贡献 Nuxt 时经过深思熟虑地使用 AI 工具，但要求所有贡献者遵循两条核心原则。

绝不要让 LLM 替你发言

  • 所有评论、issue 和 Pull Request 描述都应该用你自己的声音来写
  • 我们重视清晰、人性化的沟通，胜过完美的语法或拼写
  • 避免复制粘贴不能反映你自身理解的 AI 生成摘要

绝不要让 LLM 替你思考

  • 可以随意使用 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 模块模板。更多相关信息请参阅模块指南。

使用核心 unjs/ 库

我们推荐以下在整个生态中使用的库：

  • pathe - 通用路径工具（node path 的替代品）
  • ufo - URL 解析与拼接工具
  • obuild - 由 rolldown 驱动构建系统
  • ... 查看 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 进行 lint 和格式化，配合 @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 或 deno run lint --fix，或参考ESLint 部分了解 IDE 配置。

如果你在编辑器中安装了 Prettier，我们建议你在处理该项目时禁用它，以避免冲突。

包管理器

我们推荐将 pnpm 作为模块、库和应用的包管理器。

启用 Corepack 以确保你使用的包管理器版本与项目一致，这一点很重要。Corepack 内置于新版本的 Node.js 中，可实现无缝的包管理器集成。

要启用它，运行：

Terminal
corepack enable

你只需要在电脑上安装 Node.js 后做一次即可。

文档风格指南

文档是 Nuxt 的重要组成部分。我们的目标是成为一个直观的框架——其中很大一部分就是确保整个生态中的开发者体验和文档都尽可能完美。👌

以下是一些可能有助于改进你文档的提示：

语言

  • 使用美式英语拼写（behavior 而非 behaviour，customize 而非 customise）。
  • 工具名和项目名使用其官方大小写，即使 npm 包名是小写（例如，PostCSS 而非 postcss，Vite 而非 vite，ESLint 而非 eslint）。仅在指代包本身（例如安装说明中）时才在反引号中使用小写 npm 包名。
    Nuxt supports postcss out of the box.
    Nuxt 开箱即用地支持 PostCSS。你无需手动安装 postcss。
    常见工具名的大小写会在你运行 pnpm lint:docs 时由 case police 自动检查。

标题

  • 按照芝加哥标题大小写（Chicago title case）对标题进行首字母大写。简而言之：大写第一个词、最后一个词以及所有主要词（名词、动词、形容词、副词、代词）；小写冠词、并列连词和介词，无论长短（例如 a、and、or、with、from、to）。如有疑问，capitalizemytitle.com 可以提供帮助。
    How to contribute to the docs
    How to Contribute to the Docs
  • 标题中的代码保持原有大小写，不计入首字母大写（例如 Using useFetch in Components）。

行内代码

将以下内容用反引号包裹，以便它们渲染为行内代码：

  • 文件名和路径：nuxt.config.ts、server/api/
  • npm 包名：@nuxt/kit、postcss
  • 配置键、选项和值：ssr: false、the css 选项
  • 代码标识符，如函数、组合式函数、组件、变量和类型：useFetch、<NuxtLink>、defineNuxtConfig
  • 终端命令：npx nuxt init

工具、项目或一般概念的名称不要使用反引号（提及工具时用 Vite，而不是 vite）。

代码示例

  • 为代码块添加文件名，以便读者知道代码属于哪里。如果代码不属于某个特定文件（例如 shell 命令），请使用描述性标签如 [Terminal]。
    ```ts [nuxt.config.ts]
export default defineNuxtConfig({
  ssr: false,
})
```
  • 使示例可复制粘贴。包含必要的导入，并避免读者会粘贴到自己项目中的代码中间出现 ... 这样的占位符。读者应该能够将示例复制到他们的项目中，并只需极少改动即可运行。

链接

  • 链接到其他文档页面时，使用不带域名的相对路径：/docs/getting-started/installation，而不是 https://nuxt.com/docs/getting-started/installation。
  • 链接到外部资源时，链接到最终 URL，而不是会重定向的 URL。你可以用以下方式检查：
    Terminal
    curl -sILo /dev/null -w '%{http_code} %{url_effective}\n' https://example.com/some-page

    这会跟随任何重定向链并打印最终的状态和 URL。返回 200 状态且 URL 为你请求的地址，意味着链接没有问题。如果最终 URL 不同，则链接到那个地址。

语气

我们追求友好而专业的语气。直接对读者说话（“你”），简洁明了，并假定善意：读者来自不同的背景和经验水平，因此避免使用可能让人感到被居高临下对待的语言。可以温暖一些——文档可以有人情味——但清晰始终是第一位的。

写作风格

  • 尽可能避免使用 simply、just、obviously... 等主观词汇。
    请记住，你的读者可能有着不同的背景和经验。因此，这些词并不能传达意义，反而可能有害。
    Simply make sure the function returns a promise.
    确保该函数返回一个 promise。
  • 偏好主动语态。
    An error will be thrown by Nuxt.
    Nuxt 将抛出一个错误。
  • 在记录 API 页面（包括组合式函数、工具和组件）时，使用一致的章节名称和顺序。只包含适用的章节：
    1. Usage（用法）：解释如何使用该 API，并涵盖常见用例。
    2. Type（类型）：提供相关的 TypeScript 声明。
    3. Parameters（参数）：描述每个输入，包括其类型、默认值和可用选项。
    4. Return Values（返回值）：描述返回的值及其类型。
    5. Example（示例）：展示一个实际示例。

    使用这些确切的章节名称。例如，使用 Parameters 而不是 Params，使用 Example 而不是 Examples。
  • 在记录 API 页面（组合式函数、工具、组件）时，当引入某个功能或工具时，添加最低 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、发布说明或 Nuxt 博客。

了解如何为文档做出贡献。