Node.js / 系统课时
创建可复用 npm 包
创建可复用 npm 包
一个可复用 npm 包至少要解决三件事:消费者从哪里导入、哪些文件会被发布、发布前怎样验证。本课用一个 ESM 文本工具包完成入口与子路径导出、本地安装测试和 npm pack 检查,并说明真正发布到 npm registry 前必须确认的字段。
学习目标
- 用
package.json的exports明确定义公共 API。 - 在本地项目中安装待发布包并验证真实导入路径。
- 用
npm pack --dry-run检查发布内容,再理解npm publish的前置条件。
先定义包的公共入口
以下示例面向当前仍受支持的 Node.js 版本,使用 ESM。目录只需要 package.json、src/index.js、src/format.js 和 README.md。exports 会限制消费者能导入的公开路径,因此不要把内部文件路径当成 API。
{
"name": "@example/text-tools",
"version": "1.0.0",
"type": "module",
"description": "Small reusable text helpers for Node.js",
"exports": {
".": "./src/index.js",
"./format": "./src/format.js"
},
"files": [
"src",
"README.md"
],
"engines": {
"node": ">=20"
},
"license": "MIT"
}片段示例:这是包清单配置,不单独运行。exports["."] 定义 @example/text-tools 的主入口,exports["./format"] 定义 @example/text-tools/format 子路径;files 用白名单减少误发布测试数据、草稿和本地配置的风险。
写一个能直接导入的 API
主入口只重新导出希望长期承诺给消费者的函数。内部实现可以拆文件,但消费者不应该依赖 src 下未出现在 exports 中的路径。
// src/format.js
export function slugify(input) {
return input
.trim()
.toLowerCase()
.replace(/[^a-z0-9]+/g, "-")
.replace(/^-+|-+$/g, "");
}// src/index.js
export { slugify } from "./format.js";在包目录运行下面的命令直接验证主入口:
node --input-type=module -e "import { slugify } from './src/index.js'; console.log(slugify('Hello Node JS'))"预期输出:
hello-node-js这个测试只证明源码入口可执行,还不能证明“消费者安装后的导入方式”正确,所以发布前还要做本地安装测试。

用本地消费者验证真实安装路径
假设待测试包的目录名为 text-tools,先在它的同级位置创建临时消费者项目。npm install ../text-tools 会把本地目录作为依赖安装,适合在发布前验证包名入口和 exports。
mkdir consumer-test
cd consumer-test
npm init -y
npm install ../text-tools
node --input-type=module -e "import { slugify } from '@example/text-tools'; console.log(slugify('Local Package Test'))"预期结果:安装命令应成功退出,最后一条 Node.js 命令输出:
local-package-test如果这里出现 ERR_PACKAGE_PATH_NOT_EXPORTED,先检查消费者导入的子路径是否确实列在 exports 中;如果出现 ERR_MODULE_NOT_FOUND,检查入口文件路径是否正确,并继续用打包检查确认目标文件会进入发布包。
发布前先看 npm pack 会带上什么
在包目录运行 npm pack --dry-run。npm 会列出准备放入 tarball 的文件和包信息,但不会真正发布;这一步用于发现 .env、测试夹具、大型素材或构建产物是否被误带入。
npm pack --dry-run预期结果:命令退出码为 0,并且文件列表至少包含 package.json、README.md、src/index.js、src/format.js;不应包含本地 .env、node_modules 或未被白名单允许的项目文件。不同 npm 版本的统计字段和显示顺序可能不同,以“实际将被打包的文件集合”作为检查重点。
真正发布前还要确认包名可用、版本号未被占用、已经通过 npm login 完成身份验证。若使用公开的 scoped package,常见命令是 npm publish --access public;示例中的 @example 只用于演示,本地测试后应改成自己拥有的 scope。发布会修改远端 registry,因此不要把它放进本地验证脚本自动执行。
把版本号当成 API 承诺
version 通常遵循语义化版本:修复兼容 Bug 升补丁号,例如 1.0.0 到 1.0.1;新增向后兼容 API 升次版本号,例如到 1.1.0;删除导出、改变参数含义或让既有调用失效,应升主版本号,例如到 2.0.0。
发布前最后核对三件事:消费者只使用 exports 暴露的路径;npm pack --dry-run 中没有秘密或无关文件;README 至少写出安装命令和一个真实导入示例。这样包的入口、发布内容和使用说明才能保持一致。