NPM 包开发(三)：本地测试、发布与使用

我们已经成功地编写并构建了一个 NPM 包。现在，我们来到了最激动人心的环节：将它发布，并分享给大家！

本篇指南将覆盖一个专业开发者发布前的完整流程：

1. 本地测试：在发布前，如何在另一个项目中测试你的包，确保它能正常工作。
2. 发布到 NPM：将你的包上传到 NPM 官方仓库。
3. 在项目中使用：如何像安装其他第三方包（如 lodash）一样安装和使用你自己的包。

1. 最重要的一步：使用 npm link 进行本地测试

直接发布一个未经测试的包版本是一种非常不专业的行为。如果你的包有 Bug，所有使用者都会受到影响。因此，在发布前，我们必须在真实环境中进行本地测试。npm link 命令就是为此而生的“开发者利器”。

npm link 的原理是，它会在你的电脑上创建一个“全局快捷方式”指向你的包项目，然后你可以在任何其他项目中“连接”到这个快捷方式，从而模拟出包被安装后的效果，而无需真正地从网络上下载。

第 1 步：在 你的库项目 中，创建链接

在你的库项目（例如 my-awesome-lib）的根目录中，打开终端并运行：

npm link

这会告诉 NPM：“嘿，把这个项目注册为一个全局链接。”

第 2 步：在 你的地图项目 中，使用链接

现在，打开一个你希望使用这个库的 ArenaPro 地图项目。在该项目的根目录中，打开终端并运行：

# 将 "my-awesome-lib" 替换成你自己的包名
npm link my-awesome-lib

这条命令会在地图项目的 node_modules 文件夹里，创建一个指向你库项目的符号链接（symlink）。从地图项目的角度看，my-awesome-lib 这个包就好像是通过 npm install 安装进来的一样。

第 3 步：在地图项目中测试你的库

现在，你可以在地图项目的任意代码文件中，导入并使用你库里的函数了：

// 在你的地图项目的某个 server script 文件中
import { capitalize, clamp } from "my-awesome-lib";

const newName = capitalize("arena"); // 'Arena'
const safeHealth = clamp(120, 0, 100); // 100

console.log(newName, safeHealth);

最棒的是，这个链接是“实时”的。如果你现在回到库项目，修改了代码（比如修复了一个 Bug），你只需要：

1. 在库项目中运行 npm run build 重新构建。
2. 你的地图项目会立刻获得更新，无需任何额外操作！

通过 npm link，你可以非常高效地进行迭代开发和测试，直到你对你的包 100% 满意为止。

2. 发布到 NPM

当你通过本地测试，确认你的包已经准备好时，就可以将它发布到 NPM 仓库了。

第 1 步：登录 NPM 账户

在终端里运行：

npm login

根据提示输入你的 NPM 用户名、密码和邮箱。这是一个一次性的操作，只要你不退出登录，以后就不用再输了。（如果你没有账户，去 npmjs.com 免费注册一个）。

第 2 步：检查 package.json

发布前，最后检查一遍 package.json 文件：

• name: 必须是全局唯一的。如果一个名字已经被别人用了，你就需要换一个。一个常见的做法是使用带作用域的包名，比如 @your-npm-username/my-awesome-lib。
• version: 确保你设置了一个合适的版本号，比如 1.0.0。每次更新发布时，你都需要提升这个版本号。

第 3 步：发布！

万事俱备，只需一个命令：

npm publish

如果你的包名是带作用域的 (比如 @username/my-lib)，你需要添加一个访问标记：

npm publish --access=public

如果一切顺利，几秒钟后，你的包就会出现在 NPM 网站上！

3. 在任何项目中使用你发布的包

现在，你的包已经是一个真正的、公开的 NPM 包了。世界上任何开发者（包括你自己）都可以像使用其他任何库一样来使用它。

在一个全新的项目中，你只需：

第 1 步：安装

npm install my-awesome-lib

第 2 步：使用

import { capitalize, clamp } from "my-awesome-lib";

console.log(capitalize("hello from npm!"));

由于我们在构建时生成了 .d.ts 类型声明文件并正确配置了 package.json，你的用户将会获得完美的自动代码补全和类型检查，就像他们在使用一个专业的、成熟的库一样。

恭喜你！你已经完整地掌握了从创建、构建、发布到使用一个 NPM 包的全过程。这为你参与更广泛的开源社区合作和构建更大型的模块化项目打下了坚实的基础。

发布失败？常见问题排查

第一次执行 npm publish 时，你可能会遇到一些常见的错误，别担心，这很正常！

• 错误信息包含 403 Forbidden 或 EPERM:

  • 原因 1: 包名已被占用。 NPM 的包名是全局唯一的，换一个更有创意的名字吧！
  • 原因 2: 没有登录。 请在终端执行 npm login 并按提示输入你的 NPM 账号信息。

• 错误信息包含 402 Payment Required:

  • 原因: 你可能在 package.json 中使用了 @scope/package-name 格式的包名，但没有付费的 NPM Pro 计划。
  • 解决: 对于免费的公共包，请使用 npm publish --access public 命令来发布。

• 错误信息提示你不能发布一个已存在的版本: _ 原因: 你不能覆盖已经发布的版本。 _ 解决: 每次发布前，都需要提升版本号。最简单的方式是执行 npm version patch，它会自动修改 package.json 中的版本（例如从 1.0.0 到 1.0.1）。

---

上一篇：第二步：编写与构建