Effect 仓库的包发布校验指南对齐 exports、审计 files 并验证打包载荷【免费下载链接】effectBuild production-ready applications in TypeScript项目地址: https://gitcode.com/GitHub_Trending/ef/effect导读本文基于 Effect 官方仓库的包开发工作流中的发布环节publishing.md系统讲解一个 pnpm monorepo 在发布 npm 包前必须完成的“发布面packed surface”校验如何让开发态exports与publishConfig.exports逐键对齐、如何保证发布载荷中的文件与 AI 文档工具输出一致、以及如何通过 dry-run 打包tarball在真实发布前确认文件清单、导出映射与元数据完全符合预期。读完本文你将掌握一套可直接复用的多包仓库发布前验证流程并能对照仓库中的真实package.json理解其背后的设计意图。一、为什么需要专门的“发布面”审计Effect 是一个典型的 pnpm workspace 多包仓库packages 下同时维护effect、effect/platform-*、effect/sql-*、effect/ai-*、effect/cluster-*等数十个包。在这种规模下任何一个包都可能遇到三类典型问题开发态与发布态导出不一致开发时 TypeScript 直接指向src下的.ts源码发布后却需要指向dist下编译好的.js.d.ts两个映射只要漏改一个键消费者就会拿到错误入口。发布载荷缺文件或多文件files白名单漏掉生成文档或把内部实现文件打包出去。内部入口被意外暴露形如./internal/*的路径一旦漏配null用户就能import到仓库内部 API导致后续重构无法收紧。publishing.md 给出的应对思路是以同族中已发布的相邻包作为基准“Compare the package manifest with a neighboring published package in the same family”逐项核对三类约束再用真实的打包产物做最终验证。这一点与 SKILL.md 中“把包工作视为注册变更而非目录拷贝Treat package work as a registration change, not a directory copy”的工作流一脉相承——发布不是复制一个目录而是确保每个注册面都正确。二、对齐开发态exports与publishConfig.exports2.1 双份导出的设计动机Effect 仓库中的每个可发布包都同时维护两份导出映射以核心包 packages/effect/package.json 为最典型示例exports开发态供仓库内 TypeScript 项目引用、类型检查、测试使用目标直接指向src下的源码如.: ./src/index.tspublishConfig.exports发布态npm 发布时替换开发态导出目标指向dist下编译产物如.: ./dist/index.js。这种“按 key 对齐、仅目标不同”的写法让两个映射可以机械地互相核对开发态的每一个exports键都必须在publishConfig.exports中存在反之亦然。发布环节要求逐一检查这份对齐关系原文“Keep developmentexportsandpublishConfig.exportsaligned by key”。2.2 从源码目标到构建目标的转换规则对齐时遵循一个简单规则源码目标变成其预期的构建目标“Source targets become their intended built targets”。由于 tsconfig.base.json 开启了rewriteRelativeImportExtensions源码中的./src/index.ts会在编译时改写为./dist/index.js因此.: ./src/index.ts→.: ./dist/index.js./testing: ./src/testing/index.ts→./testing: ./dist/testing/index.js./unstable/sql: ./src/unstable/sql/index.ts→./unstable/sql: ./dist/unstable/sql/index.js通配./*: ./src/*.ts→./*: ./dist/*.js2.3 用null屏蔽内部与遗留路径对齐映射的另一个关键点是被屏蔽的内部路径和遗留路径必须保持屏蔽“blocked internal and legacy paths remain blocked”。观察 packages/effect/package.json 与publishConfig.exports中对应的键可以看到一组固定的null条目./unstable/cli/internal/*: null, ./unstable/cluster/internal/*: null, ./internal/*: null, ./index: null, ./*/index: null./internal/*、./unstable/cli/internal/*、./unstable/cluster/internal/*将内部实现目录整体封死禁止外部导入./index与./*/index封死“裸 index 入口”的遗留路径强制消费者使用显式子路径保证每个公开入口都有且只有一个发布对应物。同族包 packages/platform/node/package.json 也保持了完全一致的屏蔽策略./internal/*: null、./index: null、./*/index: null这正是“与相邻已发布包对齐”的落地体现。发布审计时应以这类同族包为模板逐个键比对差异。三、发布载荷文件审计files列表与 AI 文档拷贝工具3.1files白名单的构成每个可发布包的files字段决定了打进 tarball 的文件集合以 packages/effect/package.json 为例files: [ src/**/*.ts, dist/**/*.js, dist/**/*.js.map, dist/**/*.d.ts, dist/**/*.d.ts.map, AGENTS.md, CLAUDE.md, ai-docs/**/* ]它同时包含源码、编译产物含 source map 与声明文件以及面向 AI 的工具文档。发布环节要求逐个核对当前 AI 文档拷贝工具与files列表确保发布载荷中每一项必需文件都在原文“Check current AI documentation copy tooling and the packagefileslist for every file required in the published payload”。3.2 copy-ai-docs.mjs工具与清单的强绑定仓库用 scripts/copy-ai-docs.mjs 统一向每个可发布包注入 AI 文档其逻辑直接约束了files清单第 7 行定义了固定文件集合[AGENTS.md, CLAUDE.md, ai-docs/**/*]遍历所有packages/{*,*/*}/package.json跳过private包对每个非私有包若其files列表缺少上述任一项直接抛出错误第 22-24 行从工具层面强制“文件在清单中”随后把根目录LLMS.md拷贝为各包的AGENTS.md与CLAUDE.md并把ai-docs目录排除dist与node_modules同步进各包第 27-32 行。这意味着发布环节的“files 审计”不能只对着静态package.json看还要确认拷贝工具产出的文件名与files白名单完全吻合——二者任一改动都必须同步否则要么发布载荷缺失文档要么工具直接报错阻断构建。四、公开入口的一一对应与内部入口隔离发布面审计的第三项原则是每个公开源码入口必须恰好有一个发布对应物且没有任何内部入口被暴露原文“Ensure each public source entrypoint has exactly one published counterpart and no internal entrypoint becomes exposed”。实际操作中可归纳为三步枚举src下所有公开入口index.ts、testing/index.ts、unstable/*/index.ts等在publishConfig.exports中确认每个入口都有唯一对应目标且该目标指向dist下的编译产物反向检查凡是不属于公开入口的路径internal、dist中间文件、*/index遗留形式都必须被null或缺失键拦截。对照 packages/effect/package.json 的 17 个unstable/*子入口与 5 个null屏蔽键即可验证这一约束对新增子包例如新加入的effect/sql-pglite应参照同族 SQL 包核对同样的结构。五、dry-run 打包在真实发布前验证 tarball5.1 先跑根构建让发布载荷生成真正执行发布前的验证必须建立在真实构建产物之上。仓库根 package.json 的build脚本为tsc -b tsconfig.packages.json pnpm --recursive --parallel --filter ./packages/**/* run build node scripts/copy-ai-docs.mjs它依次完成根 TypeScript 项目引用图构建 → 各包并行执行自身buildtsc -b tsconfig.json pnpm babel其中 babel 步骤给dist产物标注annotate-pure-calls并生成 source map→ 调用 copy-ai-docs.mjs 生成发布所需的 AI 文档。只有这一串跑通dist与ai-docs才会以发布形态存在后续打包才有意义。此外正式发布脚本 package.json 的changeset-publish还会先执行node scripts/set-strip-internal.mjs该脚本scripts/set-strip-internal.mjs在发布前把 tsconfig.base.json 中的stripInternal从false翻转为true确保带internal标记的声明不会进入发布的.d.ts——这也是“发布面与开发面不同”的一个典型例证进一步说明为什么必须用真实发布配置来打包验证。5.2 生成 tarball 并检查文件清单发布前验证的核心操作是将包打包到临时目录但不发布然后检查其文件清单原文“Create a tarball in a temporary destination without publishing, inspect its file list”。常用做法# 方案一仅预览不落盘 npm pack --dry-run # 方案二打包到临时目录并指定产物名便于进一步检查 mkdir -p /tmp/effect-pack-check pnpm pack --out /tmp/effect-pack-check/effect.tgz然后解压或列目录检查 tarball 内容tar -tzf /tmp/effect-pack-check/effect.tgz核对点包括package/src/**/*.ts源码是否齐备Effect 同时发布源码便于 source map 溯源package/dist/**/*.js、.js.map、.d.ts、.d.ts.map是否与files白名单一致package/AGENTS.md、package/CLAUDE.md、package/ai-docs/**是否被 AI 文档拷贝工具正确注入不应出现internal源码、临时文件或未列入files的杂项。5.3 检查打包后的package.json只要构建过程涉及 manifest 变换就必须检查打包后的package.json原文“inspect the packedpackage.jsonwhenever manifest transformation matters”。在 npm/pnpm 的打包流程中publishConfig的内容会被合并/覆盖进最终 manifest因此重点验证exports已从src/*.ts形态切换为dist/*.js形态且键集合与开发态完全一致./internal/*、./index、./*/index等null屏蔽键仍然保留files、sideEffects: []、type: module、engines如 packages/platform/node/package.json 的node 18.0.0等元数据符合预期dependencies/peerDependencies已被解析为版本范围而非workspace:^协议例如effect: workspace:^在发布时会被替换为对应版本。5.4 完成标准按 publishing.md 的定义发布校验分支在以下条件全部满足时才算完成“This branch is complete when package and root checks pass and the packed surface contains exactly the intended files, exports, and metadata”包自身检查tsc -b、测试、公开 API 类型测试通过根级检查tsc -b tsconfig.json、check-dist-types等通过dry-run 打包出的载荷精确包含预期的文件、导出映射与元数据——不多不少。六、发布校验在整个包工作流中的位置发布环节不是孤立的。在 .agents/skills/package-development/SKILL.md 定义的包开发工作流中它位于第 4 步前面依次是以同族包为基准分类发布状态第 1 步、创建/移动源码与 manifest 文件第 2 步依赖分类见 dependencies.md、按 registration.md 核对所有注册面第 3 步包括pnpm-workspace.yaml、tsconfig.packages.json、.changeset/config.json、AI 文档拷贝工具与files清单等。只有注册面分类完毕、且该包被判定为“published package”时才进入本文所述的发布面验证最后再补根 changeset 与文档路由。因此可以把发布面审计理解为整个注册流程的“最后一公里”注册面保证包能被仓库发现与构建发布面保证包被消费者正确安装与使用。二者结合才是 Effect 仓库“production-ready”包发布的标准闭环。结语Effect 仓库的发布校验实践可以提炼为三条可迁移的经验以同族已发布包为对齐基准、用 dry-run 打包代替拍脑袋判断、把发布面约束写进工具链copy-ai-docs 的强制校验、set-strip-internal 的发布前开关。无论你是维护这个仓库的包、向其中新增子包还是在其他 pnpm monorepo 中建立发布纪律都可以直接复用这套“对齐 exports → 审计 files → 校验打包载荷”的三步流程让每一次发布都只包含你真正想交付的内容。【免费下载链接】effectBuild production-ready applications in TypeScript项目地址: https://gitcode.com/GitHub_Trending/ef/effect创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Effect 仓库的包发布校验指南：对齐 exports、审计 files 并验证打包载荷
Effect 仓库的包发布校验指南对齐 exports、审计 files 并验证打包载荷【免费下载链接】effectBuild production-ready applications in TypeScript项目地址: https://gitcode.com/GitHub_Trending/ef/effect导读本文基于 Effect 官方仓库的包开发工作流中的发布环节publishing.md系统讲解一个 pnpm monorepo 在发布 npm 包前必须完成的“发布面packed surface”校验如何让开发态exports与publishConfig.exports逐键对齐、如何保证发布载荷中的文件与 AI 文档工具输出一致、以及如何通过 dry-run 打包tarball在真实发布前确认文件清单、导出映射与元数据完全符合预期。读完本文你将掌握一套可直接复用的多包仓库发布前验证流程并能对照仓库中的真实package.json理解其背后的设计意图。一、为什么需要专门的“发布面”审计Effect 是一个典型的 pnpm workspace 多包仓库packages 下同时维护effect、effect/platform-*、effect/sql-*、effect/ai-*、effect/cluster-*等数十个包。在这种规模下任何一个包都可能遇到三类典型问题开发态与发布态导出不一致开发时 TypeScript 直接指向src下的.ts源码发布后却需要指向dist下编译好的.js.d.ts两个映射只要漏改一个键消费者就会拿到错误入口。发布载荷缺文件或多文件files白名单漏掉生成文档或把内部实现文件打包出去。内部入口被意外暴露形如./internal/*的路径一旦漏配null用户就能import到仓库内部 API导致后续重构无法收紧。publishing.md 给出的应对思路是以同族中已发布的相邻包作为基准“Compare the package manifest with a neighboring published package in the same family”逐项核对三类约束再用真实的打包产物做最终验证。这一点与 SKILL.md 中“把包工作视为注册变更而非目录拷贝Treat package work as a registration change, not a directory copy”的工作流一脉相承——发布不是复制一个目录而是确保每个注册面都正确。二、对齐开发态exports与publishConfig.exports2.1 双份导出的设计动机Effect 仓库中的每个可发布包都同时维护两份导出映射以核心包 packages/effect/package.json 为最典型示例exports开发态供仓库内 TypeScript 项目引用、类型检查、测试使用目标直接指向src下的源码如.: ./src/index.tspublishConfig.exports发布态npm 发布时替换开发态导出目标指向dist下编译产物如.: ./dist/index.js。这种“按 key 对齐、仅目标不同”的写法让两个映射可以机械地互相核对开发态的每一个exports键都必须在publishConfig.exports中存在反之亦然。发布环节要求逐一检查这份对齐关系原文“Keep developmentexportsandpublishConfig.exportsaligned by key”。2.2 从源码目标到构建目标的转换规则对齐时遵循一个简单规则源码目标变成其预期的构建目标“Source targets become their intended built targets”。由于 tsconfig.base.json 开启了rewriteRelativeImportExtensions源码中的./src/index.ts会在编译时改写为./dist/index.js因此.: ./src/index.ts→.: ./dist/index.js./testing: ./src/testing/index.ts→./testing: ./dist/testing/index.js./unstable/sql: ./src/unstable/sql/index.ts→./unstable/sql: ./dist/unstable/sql/index.js通配./*: ./src/*.ts→./*: ./dist/*.js2.3 用null屏蔽内部与遗留路径对齐映射的另一个关键点是被屏蔽的内部路径和遗留路径必须保持屏蔽“blocked internal and legacy paths remain blocked”。观察 packages/effect/package.json 与publishConfig.exports中对应的键可以看到一组固定的null条目./unstable/cli/internal/*: null, ./unstable/cluster/internal/*: null, ./internal/*: null, ./index: null, ./*/index: null./internal/*、./unstable/cli/internal/*、./unstable/cluster/internal/*将内部实现目录整体封死禁止外部导入./index与./*/index封死“裸 index 入口”的遗留路径强制消费者使用显式子路径保证每个公开入口都有且只有一个发布对应物。同族包 packages/platform/node/package.json 也保持了完全一致的屏蔽策略./internal/*: null、./index: null、./*/index: null这正是“与相邻已发布包对齐”的落地体现。发布审计时应以这类同族包为模板逐个键比对差异。三、发布载荷文件审计files列表与 AI 文档拷贝工具3.1files白名单的构成每个可发布包的files字段决定了打进 tarball 的文件集合以 packages/effect/package.json 为例files: [ src/**/*.ts, dist/**/*.js, dist/**/*.js.map, dist/**/*.d.ts, dist/**/*.d.ts.map, AGENTS.md, CLAUDE.md, ai-docs/**/* ]它同时包含源码、编译产物含 source map 与声明文件以及面向 AI 的工具文档。发布环节要求逐个核对当前 AI 文档拷贝工具与files列表确保发布载荷中每一项必需文件都在原文“Check current AI documentation copy tooling and the packagefileslist for every file required in the published payload”。3.2 copy-ai-docs.mjs工具与清单的强绑定仓库用 scripts/copy-ai-docs.mjs 统一向每个可发布包注入 AI 文档其逻辑直接约束了files清单第 7 行定义了固定文件集合[AGENTS.md, CLAUDE.md, ai-docs/**/*]遍历所有packages/{*,*/*}/package.json跳过private包对每个非私有包若其files列表缺少上述任一项直接抛出错误第 22-24 行从工具层面强制“文件在清单中”随后把根目录LLMS.md拷贝为各包的AGENTS.md与CLAUDE.md并把ai-docs目录排除dist与node_modules同步进各包第 27-32 行。这意味着发布环节的“files 审计”不能只对着静态package.json看还要确认拷贝工具产出的文件名与files白名单完全吻合——二者任一改动都必须同步否则要么发布载荷缺失文档要么工具直接报错阻断构建。四、公开入口的一一对应与内部入口隔离发布面审计的第三项原则是每个公开源码入口必须恰好有一个发布对应物且没有任何内部入口被暴露原文“Ensure each public source entrypoint has exactly one published counterpart and no internal entrypoint becomes exposed”。实际操作中可归纳为三步枚举src下所有公开入口index.ts、testing/index.ts、unstable/*/index.ts等在publishConfig.exports中确认每个入口都有唯一对应目标且该目标指向dist下的编译产物反向检查凡是不属于公开入口的路径internal、dist中间文件、*/index遗留形式都必须被null或缺失键拦截。对照 packages/effect/package.json 的 17 个unstable/*子入口与 5 个null屏蔽键即可验证这一约束对新增子包例如新加入的effect/sql-pglite应参照同族 SQL 包核对同样的结构。五、dry-run 打包在真实发布前验证 tarball5.1 先跑根构建让发布载荷生成真正执行发布前的验证必须建立在真实构建产物之上。仓库根 package.json 的build脚本为tsc -b tsconfig.packages.json pnpm --recursive --parallel --filter ./packages/**/* run build node scripts/copy-ai-docs.mjs它依次完成根 TypeScript 项目引用图构建 → 各包并行执行自身buildtsc -b tsconfig.json pnpm babel其中 babel 步骤给dist产物标注annotate-pure-calls并生成 source map→ 调用 copy-ai-docs.mjs 生成发布所需的 AI 文档。只有这一串跑通dist与ai-docs才会以发布形态存在后续打包才有意义。此外正式发布脚本 package.json 的changeset-publish还会先执行node scripts/set-strip-internal.mjs该脚本scripts/set-strip-internal.mjs在发布前把 tsconfig.base.json 中的stripInternal从false翻转为true确保带internal标记的声明不会进入发布的.d.ts——这也是“发布面与开发面不同”的一个典型例证进一步说明为什么必须用真实发布配置来打包验证。5.2 生成 tarball 并检查文件清单发布前验证的核心操作是将包打包到临时目录但不发布然后检查其文件清单原文“Create a tarball in a temporary destination without publishing, inspect its file list”。常用做法# 方案一仅预览不落盘 npm pack --dry-run # 方案二打包到临时目录并指定产物名便于进一步检查 mkdir -p /tmp/effect-pack-check pnpm pack --out /tmp/effect-pack-check/effect.tgz然后解压或列目录检查 tarball 内容tar -tzf /tmp/effect-pack-check/effect.tgz核对点包括package/src/**/*.ts源码是否齐备Effect 同时发布源码便于 source map 溯源package/dist/**/*.js、.js.map、.d.ts、.d.ts.map是否与files白名单一致package/AGENTS.md、package/CLAUDE.md、package/ai-docs/**是否被 AI 文档拷贝工具正确注入不应出现internal源码、临时文件或未列入files的杂项。5.3 检查打包后的package.json只要构建过程涉及 manifest 变换就必须检查打包后的package.json原文“inspect the packedpackage.jsonwhenever manifest transformation matters”。在 npm/pnpm 的打包流程中publishConfig的内容会被合并/覆盖进最终 manifest因此重点验证exports已从src/*.ts形态切换为dist/*.js形态且键集合与开发态完全一致./internal/*、./index、./*/index等null屏蔽键仍然保留files、sideEffects: []、type: module、engines如 packages/platform/node/package.json 的node 18.0.0等元数据符合预期dependencies/peerDependencies已被解析为版本范围而非workspace:^协议例如effect: workspace:^在发布时会被替换为对应版本。5.4 完成标准按 publishing.md 的定义发布校验分支在以下条件全部满足时才算完成“This branch is complete when package and root checks pass and the packed surface contains exactly the intended files, exports, and metadata”包自身检查tsc -b、测试、公开 API 类型测试通过根级检查tsc -b tsconfig.json、check-dist-types等通过dry-run 打包出的载荷精确包含预期的文件、导出映射与元数据——不多不少。六、发布校验在整个包工作流中的位置发布环节不是孤立的。在 .agents/skills/package-development/SKILL.md 定义的包开发工作流中它位于第 4 步前面依次是以同族包为基准分类发布状态第 1 步、创建/移动源码与 manifest 文件第 2 步依赖分类见 dependencies.md、按 registration.md 核对所有注册面第 3 步包括pnpm-workspace.yaml、tsconfig.packages.json、.changeset/config.json、AI 文档拷贝工具与files清单等。只有注册面分类完毕、且该包被判定为“published package”时才进入本文所述的发布面验证最后再补根 changeset 与文档路由。因此可以把发布面审计理解为整个注册流程的“最后一公里”注册面保证包能被仓库发现与构建发布面保证包被消费者正确安装与使用。二者结合才是 Effect 仓库“production-ready”包发布的标准闭环。结语Effect 仓库的发布校验实践可以提炼为三条可迁移的经验以同族已发布包为对齐基准、用 dry-run 打包代替拍脑袋判断、把发布面约束写进工具链copy-ai-docs 的强制校验、set-strip-internal 的发布前开关。无论你是维护这个仓库的包、向其中新增子包还是在其他 pnpm monorepo 中建立发布纪律都可以直接复用这套“对齐 exports → 审计 files → 校验打包载荷”的三步流程让每一次发布都只包含你真正想交付的内容。【免费下载链接】effectBuild production-ready applications in TypeScript项目地址: https://gitcode.com/GitHub_Trending/ef/effect创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考