用途:让 npm 包在声明支持的各类消费环境中正确安装与解析,涉及模块格式、exports 映射、类型声明与打包内容。它针对的典型问题:未核查消费端 Node 版本就断言只需 ESM、exports 映射中类型无法解析、发布包中混入源码与 CI 无关文件。
主要能力:依据 package.json#engines 与消费现实决定格式(ESM 优先而非一律 ESM);按需选择双格式并处理双包危害;显式编写 exports 映射(含 types 条件位置、子路径导出、sideEffects);使用 tsdown 作为默认构建工具(tsup 需说明理由),开启声明并匹配 engines;通过 files 白名单保持 tarball 整洁。
使用方式:先据证据定格式,再写 exports,构建,清理 tarball,最后运行门禁脚本:bash "${CLAUDE_SKILL_DIR}/scripts/check_package.sh",该脚本执行 npm pack 试运行检查、publint 与 arethetypeswrong,发现任何问题即以非零状态退出。消费端报错(如 ERR_REQUIRE_ESM、types not found)时先确认消费端 Node 与模块环境,再在文档化支持范围、真实双构建或修 exports 之间选择,不可盲目加 CJS。
适用场景:npm 包发布前的 packaging 配置与校验。限制:不负责版本号、changelog、发布、OIDC(属 node-release);不负责声明生成/tsconfig(属 node-typescript);不负责依赖卫生(属 node-supply-chain)。修改已发布包的格式或 exports 属 semver-major。双包危害真实存在,单例/状态包需按 playbook 缓解或改为带文档范围的 ESM-only。attw 报错信息晦涩,需对照 playbook 映射到具体 exports 修复。require(esm) 支持矩阵需在使用时对照 nodejs.org 文档重新核实。Node/npx 不可用时脚本会给出提示并降级。