node-packaging

node-packaging

制作一个能为你声称支持的每种使用场景正确安装和解析的包——包括模块格式、导出映射、类型和 tarball 内容。 此技能修复的问题：模型宣称“现在只支持 ESM 没问题”，却不检查使用方的 Node 版本范围；编写的导出映射无法解析类型；发布的 tarball 塞满了源代码和 CI 垃圾文件。

不适用场景

• 升级版本、编写变更日志、发布、OIDC → node-release。
• 声明文件的生成 / tsconfig → node-typescript（此技能负责使用方如何解析已生成的内容）。
• 依赖项卫生 → node-supply-chain。

工作流

1. 依据证据决定格式，而非追逐潮流——优先 ESM，而非始终 ESM： 阅读 package.json#engines 和使用方的实际情况。require(esm) 只在特定 Node 版本系列中可用，且有实际限制（所需依赖图中不能有顶层 await）——支持矩阵和决策框架见 references/packaging-playbook.md。如果较旧的引擎、工具或声明的使用方有此需求，就采用 ESM+CJS 双格式，并根据操作手册采取双包风险缓解措施。
2. 明确编写导出映射（操作手册中包含 ESM-only 和双格式示例）： 正确放置 types 条件；仅为受支持的 API 导出子路径；在适用时设置 sideEffects。
3. 构建：当前默认使用 tsdown（有合理说明时可用 tsup）——启用声明文件生成，目标版本与 engines 匹配。
4. 保持 tarball 整洁：使用 files 白名单（绝不翻查 .npmignore 历史），设置 engines，并在仓库固定了包管理器时设置 packageManager。
5. 门禁——绝不跳过：

   bash "${CLAUDE_SKILL_DIR}/scripts/check_package.sh"
   

   （检查 npm pack dry-run + publint + arethetypeswrong；确切命令见脚本；发现任何问题都会以非零状态退出。）
6. 诊断使用方错误（ERR_REQUIRE_ESM、“找不到类型”）：操作手册提供决策树——先确定使用方的 Node/模块上下文；可选方案包括明确支持范围、真正的双格式构建，或修正导出映射。 绝不要盲目添加 CJS。

输出规范

明确的导出映射；记录格式决策及其所依据的 engines；构建产物必须与导出映射声明的内容完全一致；files 白名单；两个门禁（publint、attw）均无问题；已检查 npm pack --dry-run 生成的 tarball。更改已发布包的格式或导出映射属于 semver-major——请明确说明。

注意事项

• 双包风险（两个模块实例）确实存在——单例/有状态包需要采用操作手册中的缓解措施，或在记录明确支持范围后仅使用 ESM。
• attw 的失败信息往往晦涩难懂；操作手册将其代码对应到具体的导出映射修复方法。
• engines 会影响后续的一切（node-ci 中的 CI 矩阵、此处的格式选择）——应谨慎设置，绝不要默默继承。
• 对 require(esm) 支持矩阵按版本设门槛——使用时请根据 nodejs.org 文档重新核实 Node 版本范围。

文件

• references/packaging-playbook.md — require(esm) 矩阵、格式决策框架、导出映射示例、打包工具状态、风险缓解措施、错误决策树。
• scripts/check_package.sh — pack dry-run + publint + attw 门禁；发现问题时以非零状态退出；Node/npx 不可用时会显示清晰提示并降级处理。