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。

json
{
  "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 中的路径。

js
// src/format.js
export function slugify(input) {
  return input
    .trim()
    .toLowerCase()
    .replace(/[^a-z0-9]+/g, "-")
    .replace(/^-+|-+$/g, "");
}
js
// src/index.js
export { slugify } from "./format.js";

在包目录运行下面的命令直接验证主入口:

bash
node --input-type=module -e "import { slugify } from './src/index.js'; console.log(slugify('Hello Node JS'))"

预期输出:

text
hello-node-js

这个测试只证明源码入口可执行,还不能证明“消费者安装后的导入方式”正确,所以发布前还要做本地安装测试。

npm 包从源码、exports 到打包与消费者导入的关系

用本地消费者验证真实安装路径

假设待测试包的目录名为 text-tools,先在它的同级位置创建临时消费者项目。npm install ../text-tools 会把本地目录作为依赖安装,适合在发布前验证包名入口和 exports。

bash
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 命令输出:

text
local-package-test

如果这里出现 ERR_PACKAGE_PATH_NOT_EXPORTED,先检查消费者导入的子路径是否确实列在 exports 中;如果出现 ERR_MODULE_NOT_FOUND,检查入口文件路径是否正确,并继续用打包检查确认目标文件会进入发布包。

发布前先看 npm pack 会带上什么

在包目录运行 npm pack --dry-run。npm 会列出准备放入 tarball 的文件和包信息,但不会真正发布;这一步用于发现 .env、测试夹具、大型素材或构建产物是否被误带入。

bash
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 至少写出安装命令和一个真实导入示例。这样包的入口、发布内容和使用说明才能保持一致。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

创建可复用 npm 包

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通