package-publishing

软件包发布

概述

涵盖现代 npm 软件包编写：使用 exports 字段配置 package.json、构建双格式 ESM/CJS、TypeScript 类型声明，以及通过溯源信息实现安全的发布工作流。

适用场景： 配置软件包入口点、设置条件导出、构建双格式软件包、发布带作用域的软件包，或排查模块解析问题。

不适用场景： 应用级打包（Vite/webpack 应用配置）、单体仓库工作区编排（Turborepo/Nx）、私有注册表设置（Verdaccio/Artifactory）。

快速参考

模式	字段 / 命令	要点
入口点	package.json 中的 exports	取代 main/module；封装内部实现
CJS 回退	main	供不支持 exports 的旧版使用者使用
ESM 入口	module	打包工具约定；Node.js 不使用
类型声明	exports 中的 types 条件	必须列在每个条件块的首位
子路径导出	"./utils": { ... }	提供简洁的公共 API；阻止深层导入
条件导出	import/require 条件	根据使用者切换 ESM 与 CJS
软件包类型	"type": "module"	使 .js 文件采用 ESM；CommonJS 请使用 .cjs
副作用	"sideEffects": false	在打包工具中启用摇树优化
对等依赖	peerDependencies	共享的运行时依赖（React、Vue 等）
引擎约束	"engines": { "node": ">=18" }	说明最低 Node.js 版本
文件允许列表	"files": ["dist"]	控制发布到 npm 的内容
发布前检查	"prepublishOnly": "npm run build"	确保发布前执行构建
试运行	npm pack --dry-run	发布前预览软件包内容
溯源信息	--provenance 标志或可信发布者	对构建进行加密证明
带作用域的发布	--access public	首次发布带作用域的软件包时必需

常见错误

错误	正确做法
在导出配置中将 types 放在 default 之后	types 必须是每个导出块中的第一个条件
在导出配置中缺少 "./package.json"	添加 "./package.json": "./package.json"，以兼容工具
import 和 require 使用不同的 API	使用相同的 API 表面；编写 ESM 源代码，再转译为 CJS
为新软件包使用 main，却不使用 exports	使用 exports 作为主要入口点定义
.js ESM 输出未设置 "type": "module"	设置 "type": "module"，或明确使用 .mjs 扩展名
发布 src/ 或 node_modules/	使用 "files" 允许列表，仅包含 dist/
没有 prepublishOnly 脚本	添加构建步骤，避免发布过时的构建产物
库使用 default 导出	优先使用命名导出，以确保跨工具行为一致
发布前未使用 npm pack 测试	务必先试运行，检查软件包内容和大小
框架插件未声明 peerDependencies	将共享的运行时依赖声明为对等依赖
发布时未提供来源证明	启用来源证明，确保供应链透明度
软件包为 "type": "module" 时，CJS 使用 .d.ts	CJS 类型声明使用 .d.cts；ESM 使用 .d.ts 或 .d.mts

委派

• 构建工具配置：使用 Explore Agent 检查 tsup/unbuild/rollup 配置
• 类型解析调试：使用 Task Agent 和 "Are the Types Wrong?"（attw）
• 发布流程审查：委派给 code-reviewer Agent

参考资料

• Package.json 配置：exports、main、types、files、engines、peerDependencies
• 构建脚本、prepublishOnly、npm pack、来源证明、带作用域的软件包
• ESM/CJS 双格式构建、条件导出、类型声明