开源维护者发布 npm 包指南

由 Mux 主办的 DEV 全球展示挑战赛：展示你的项目！

JavaScript 社区建立在开源之上，能够回馈社区令人倍感欣慰。然而，第一次发布软件包可能会让人感到有些畏惧，即使对于经验丰富的作者来说，发布候选版本也可能有些棘手。我希望能够提供一些见解和实用技巧，尤其对新手作者而言。

我拥有两个开源库：一个名为draftjs-md-converter的 DraftJS 小工具库，以及一个名为react-native-app-auth的 React Native 安全库。我当然不像某些人那样深度参与开源项目，但我独自负责发布这些库的新版本已有数年之久，所以我认为我的经验足以支撑我写这篇博文！我还记得第一次发布库时的忐忑不安，也依然记得发布候选版本时的忐忑心情。撰写这篇文章的目的是为了提供一份关于如何发布软件包的指南：既是为新手开发者提供的全面指导，也是为未来的自己提供的一次实践检验。

我将介绍以下内容：

• 设置用于发布的存储库
• 发布软件包（初始版本）
• 版本控制
• 发布软件包（后续版本）
• 发布 alpha/beta/候选版本

你可以使用 npm 或 yarn，完全取决于你。发布命令是相同的。我全程都会使用 npm。

设置用于发布的存储库

在运行publish命令之前，您应该检查您的软件包是否处于可以发布的状态。以下是一些您可能需要考虑的事项：

检查软件包名称

该name字段package.json将作为您已发布软件包的名称。例如，如果您将软件包命名为 `<package_name>` package-name，用户将使用该名称导入它。

import ... from "package-name";

名称必须是唯一的，因此请确保该名称在https://www.npmjs.com/上可用，否则您的发布命令将失败。

设置初始版本

该version属性package.json将决定发布时软件包的版本。对于初始版本，您可以使用：

{
  "version": "0.0.1"
}

或者

{
  "version": "1.0.0"
}

NPM 包使用语义化版本控制（semver），这意味着版本号由三个数字组成：主版本号、次版本号和补丁版本号。我们将在“版本控制”部分详细讨论版本控制。

请确保您的代码仓库不是私有的。

您package.json可能有一个属性"private": true。这是一个内置的保护机制，可以防止您意外发布本应私有的内容。如果您正在构建非开源项目（例如个人项目或客户项目），通常建议使用此属性。但是，如果您要将仓库发布为软件包，则应删除此行。

添加许可证

请确保您已在配置文件中设置许可证package.json。这样做是为了让其他人知道您允许他们如何使用您的软件包。最常见的许可证是“MIT”和“Apache 2.0”。它们都属于宽松许可证，允许用户出于任何目的分发、修改或以其他方式使用该软件。您可以在这里阅读更多关于它们区别的信息。我一直使用“MIT”许可证。

检查入口

该main字段package.json定义了软件包的主入口文件。用户导入软件包后将访问此文件。它通常类似于 `/etc/package.json` 或 `/etc/package.json`，./index.js具体./src/index.js取决于入口文件的位置。

限制要发布的文件。

默认情况下，发布软件包会发布目录中的所有内容。有时您可能不希望这样做，例如，如果您的仓库包含示例文件夹，或者您有一个构建步骤，并且只想发布构建后的包。为此，`files`字段中有一个`files`package.json字段。如果省略该字段，则其默认值为 `null` ["*"]；但如果设置了该字段，则它仅包含数组中列出的文件和目录。请注意，某些文件始终包含在内，即使它们未列出：package.json`/ etc/example/`、` / etc/example/`、`/etc/example/` README、 ` /etc /example/` 以及 `/etc/main/` 字段中的文件。CHANGES / CHANGELOG / HISTORYLICENSE / LICENCENOTICE

添加构建步骤

有时，您可能需要一个构建步骤。例如，如果您使用 Flow、TypeScript 或一些并非所有浏览器都支持的前沿 JavaScript 特性编写了软件包，并且想要将软件包编译/转译为任何人都可以使用的纯 JavaScript，那么您可以使用prepublish如下脚本：

{
  "scripts": {
    "prepublish": "npm run your-build-script"
  }
}

当您运行发布命令时，此脚本将自动运行。例如，在本软件包中，我使用该prepublish脚本在目录中重新构建应用程序dist。另请注意，main此处的字段package.json已设置为 true，"main": "dist/index.js"因为我希望用户能够访问已构建的文件。

还有其他一些内置脚本可用于各种情况，但这是我在发布软件包时唯一用到的脚本。您可以在这里阅读更多关于其他可用脚本的信息。

发布软件包（初始版本）

克隆你的仓库，并确保你位于最新master分支（或你的主分支）上，且没有未提交的更改。

如果您还没有账户，请在https://www.npmjs.com/上创建一个，并使用以下凭据在您的终端上登录：

npm login

最后，在你的项目仓库中运行：

npm publish

如果您已设置双因素身份验证，发布完成前终端会提示您进行验证。命令成功完成后，您应该可以立即在https://www.npmjs.com/package/package-name看到您的软件包，其中package-namepackage-name 是您在 npm 文件中设置的软件包名称package.json。其他人可以使用以下命令安装您的软件包：

npm install package-name

版本控制

发布软件包的后续版本需要更多考虑，因为我们现在需要考虑版本控制。如上所述，npm 软件包使用语义化版本控制（semver）。这意味着版本分为三种类型：主版本号（Major）、次版本号（Minor）和补丁版本号（Patch），您应该使用这些版本号来传达库中发生的变更类型。

• 重大变更包括与先前版本不兼容的任何内容
• 小幅改动通常包括新功能和较大的错误修复。
• 补丁更新是指对微小的错误进行修复或添加新的内容。

需要注意的是，语义化版本控制（semver）的命名方式有点误导性，尤其是在“主版本号”（major）方面——主版本号的发布并不一定意味着发生了很大的变化。它指的是从前一个版本到当前版本之间存在不兼容的变更，库的用户可能需要修改代码才能兼容最新版本。例如，更改导出函数的名称或参数顺序就属于主版本号的变更。很多维护者倾向于将所有不兼容的变更集中起来，一次性发布，以尽量减少主版本号的更新频率。

之所以只在主要版本中进行破坏性更改，是因为您的库的用户可能会默默地选择加入所有未来的补丁和次要版本，所以下次他们运行时，npm install您可能会破坏他们的构建。

其中package.json，此操作通过 ~ 和 ^ 进行沟通，其中 ~ 选择加入所有未来的补丁版本，而 ^ 选择加入所有未来的补丁和次要版本：

~1.2.3将匹配所有1.2.x版本，但会遗漏1.3.0

^1.2.3将与任何1.x.x版本同步发布1.3.0，但会推迟发布2.0.0。

附注：当主版本为 1 时0，该软件包被认为是不稳定的，因此 ^ 的作用与 ~ 相同，对于主版本 1 之前的所有版本，您可以在发布minor版本中发布重大更改。

没有选项可以选择接收所有未来主要版本的更新，因为预计这些版本都会出现重大变更，因此需要手动升级。来源。

发布软件包（后续版本）

这是在初始版本发布之后进行后续版本发布的方法。和之前一样，您应该确保当前位于主分支上，并且没有未提交的更改。考虑一下这次发布的版本类型：主版本、次版本还是补丁版本。现在，运行命令来递增工作目录中的版本号，根据更改类型使用major` --version`minor或 ` --version`：patch

npm version minor

这是一种便捷的方法，它能做到以下两点：

• package.json根据更改类型递增版本号
• 提交此版本号
• .git在您的仓库中为当前版本创建一个标签

现在只需像之前一样运行发布命令即可：

npm publish

务必确保在发布前进行版本更新。如果尝试发布同一版本的库两次，命令将会失败。

最后，您需要推送版本号提升的提交和标签：

git push
git push --tags

请注意，您需要使用该--tags标志分别推送标签。

如果您使用 GitHub 托管您的代码仓库，标签将显示在代码仓库的“发布”选项卡下，例如https://github.com/kadikraman/draftjs-md-converter/releases

为新标签编写一些发布说明是个好习惯。我通常也会利用这个空间感谢所有贡献者！

发布 alpha/beta/候选版本

alpha/beta/候选发布版本通常是主要版本的早期访问版本。当您准备进行重大更改时，您可能希望让用户有机会先试用新版本（需用户选择加入），但同时也要让他们意识到新版本可能不稳定。

我们想要实现的目标是“悄悄”发布一个新版本，只有感兴趣的用户才能选择加入。

我们来看看如何创建候选版本。假设您当前正在使用某个版本v3.4.5，并且想要为该版本创建一个候选版本v4。

首先，我们递增版本号。该npm version命令允许您提供自定义版本号。在本例中，我们将版本号设置为 v4 的第一个候选版本：

npm version 4.0.0-rc1

和之前一样，此操作会执行版本号更新、提交更改并创建标签。现在要发布软件包。这是最关键的一步，因为您需要确保所有用户默认情况下都不会获得此候选版本。

发布命令有一个--tag参数，默认值为“latest”。这意味着，无论何时有人npm install访问你的库，他们都会获得带有“latest”标签的最新发布版本。因此，我们只需要提供一个不同的标签即可。这个标签可以是任何内容，我通常使用“next”。

npm publish --tag next

这将以“next”标签发布您的软件包，因此安装 `npm install` 的用户npm install package-name仍将获得`npm install` v3.4.5，而安装 `npm install`npm install package-name@next或 ` npm install` 的用户npm install package-name@4.0.0-rc1将获得您的候选版本。请注意，如果您使用“next”标签发布另一个候选版本，则所有安装 `npm install` 的用户都npm install package-name@next将获得最新版本。

当您准备发布下一个主要版本时，您可以运行npm version major（这将把版本号提升到4.0.0），然后npm publish照常运行。

结论

差不多就是这样了！发布软件包一开始可能会有点吓人，但就像任何事情一样，做得越多就越容易。

感谢您为开源项目做出贡献！