通过 100 多个技巧学习 Nuxt！
55.5K

贡献

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

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

生态系统

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

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

如何贡献

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

查看您想要帮助的项目的 issue 和讨论。例如，这里是 Nuxt 3 的问题板和讨论。帮助其他用户、分享解决方法、创建重现或甚至稍微研究一下错误并分享您的发现都会产生巨大的影响。

创建 Issue

感谢您抽出时间创建 issue！❤️

  • 报告错误：查看我们的指南，了解在打开 issue 之前需要做的一些事情。
  • 功能请求：检查是否已经存在涵盖您心中功能范围的 issue 或讨论。如果该功能针对 Nuxt 生态系统的另一部分（例如模块），请考虑首先在那里提出功能请求。如果您心中的功能是通用的或 API 不是很清楚，请考虑在 Ideas 部分打开一个讨论，以便首先与社区讨论。

在响应 issue 时，我们将尽力遵循我们的内部 issue 决策流程图。

发送拉取请求

我们始终欢迎拉取请求！❤️

开始之前

在修复错误之前，我们建议您检查是否有描述它的 issue，因为它可能是文档问题或者有一些上下文信息可能会有所帮助。

如果您正在处理某个功能，那么我们要求您首先打开一个功能请求 issue，与维护人员讨论该功能是否是需要的以及这些功能的设计。这有助于为维护人员和贡献者节省时间，并意味着可以更快地交付功能。在拉取请求中构建功能之前，issue 应由框架团队成员确认。

对于拼写错误修复，建议将多个拼写错误修复批处理到一个拉取请求中，以保持更清晰的提交历史记录。

对于 Nuxt 本身较大的更改，我们建议您首先创建一个 Nuxt 模块并在其中实现该功能。这可以快速进行概念验证。然后，您可以以讨论的形式创建 RFC。随着用户采用它并收集反馈，它可以被改进并添加到 Nuxt 核心或继续作为独立模块。

提交约定

我们使用约定式提交来编写提交消息，这允许根据提交自动生成更改日志。如果您还不熟悉它，请阅读该指南。

请注意，fix: 和 feat: 用于实际的代码更改（可能会影响逻辑）。对于拼写错误或文档更改，请改用 docs: 或 chore:

  • fix: typo -> docs: fix typo

如果您正在使用 monorepo 的项目（如 nuxt/nuxt），请确保在括号中指定提交的主要范围。例如：feat(nuxi): add 'do-magic' command。

发出拉取请求

如果您不知道如何发送拉取请求，我们建议您阅读该指南。

发送拉取请求时，请确保您的 PR 标题也遵循提交约定。

如果您的 PR 修复或解决了现有 issue，请确保在 PR 说明中提及它们。

一个 PR 中有多个提交是可以的；您无需为您的更改进行 rebase 或强制推送，因为我们在合并时将使用 Squash and Merge 将提交合并为一个提交。

我们不会添加任何提交钩子以允许快速提交。但在您发出拉取请求之前，您应该确保任何 lint/测试脚本都已通过。

一般来说，还请确保 PR 中没有不相关的更改。例如，如果您的编辑器对您编辑的文件中的其他位置的空格或格式进行了任何更改，请还原这些更改，以便更清楚地了解您的 PR 更改的内容。并且请避免在单个 PR 中包含多个不相关的功能或修复。如果可以将它们分开，则最好有多个 PR 来单独审查和合并。一般来说，PR 应该只做一件事。

在您发出拉取请求后

在您发出拉取请求后，我们将尽力及时审查它。

如果我们将其分配给维护人员，则意味着该人将特别注意审查它并实施可能需要的任何更改。

如果我们请求对 PR 进行更改，请忽略红色文本！这并不意味着我们认为这是一个糟糕的 PR，这只是为了方便一眼看出拉取请求列表的状态。

如果我们将 PR 标记为“待定”，则表示我们可能还有其他任务需要完成才能审查 PR - 这只是一个内部的自我提醒，并不一定反映 PR 的想法好坏。我们会尽力通过评论解释待定状态的原因。

在响应和审查拉取请求时，我们会尽力遵循我们的 PR 决策流程图。

创建模块

如果您用 Nuxt 构建了一些很棒的东西，为什么不将其提取为模块，以便与他人共享？我们已经有许多优秀的模块，但总有空间容纳更多。

如果您在构建过程中需要帮助，请随时与我们联系。

发起 RFC

我们强烈建议首先创建一个模块来测试大型新功能并获得社区采用。

如果您已经这样做，或者不适合创建新模块，请首先创建一个新的讨论。确保尽可能清楚地解释您的想法。包括新 API 的代码示例或函数签名。参考现有问题或痛点，并附上示例。

如果我们认为这应该是一个 RFC，我们会将类别更改为 RFC，并更广泛地传播以征求反馈。

RFC 随后将经历以下阶段

  • rfc: active - 当前开放评论
  • rfc: approved - 已获得 Nuxt 团队批准
  • rfc: ready to implement - 已创建并分配了一个问题以供实施
  • rfc: shipped - 已实施
  • rfc: archived - 未批准，但已存档以供将来参考

生态系统中的约定

以下约定在 nuxt/ 组织内是必需的，并建议生态系统中的其他维护人员也遵循。

模块约定

模块应遵循Nuxt 模块模板。有关更多信息，请参阅模块指南。

使用核心 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": "[email protected]"
}

使用 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 版本中，可实现无缝的包管理器集成。

要启用它，请运行

终端
corepack enable

您只需在计算机上安装 Node.js 后执行一次此操作。

文档风格指南

文档是 Nuxt 的重要组成部分。我们的目标是成为一个直观的框架 - 而这很大一部分在于确保开发人员体验和文档在整个生态系统中都是完美的。👌

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

  • 尽可能避免使用诸如简单地、仅仅、显然...等主观词语。
    请记住，您的读者可能具有不同的背景和经验。因此，这些词语不传达意义，并且可能是有害的。
    只需确保该函数返回一个 Promise。
    确保该函数返回一个 promise。
  • 首选主动语态。
    Nuxt 将抛出一个错误。
    Nuxt 将抛出一个错误。
了解如何为文档做出贡献。

报告错误

在开源中，最有价值的角色之一是花时间以有用的方式报告错误。

框架

关于对框架存储库的贡献的一些具体要点。