@composy/pack
v0.0.2
Published
Shared tsup presets, CLI workflow, and post-build tooling for LDesign packages
Maintainers
Readme
第六轮:后端真实运行统计、内存门禁、产物体积预算(2026-10)
本轮所有附加能力均为 opt-in:正常 pack build、pack analyze(无预算)仍保持原有行为。构建监控的是 Node 子进程,不是父进程的 process.memoryUsage()。
# 单次后端调用的真实墙钟耗时,Linux 下同时输出采样进程树峰值 RSS
pack build --no-version-prompt --profile
# Linux 专属:采样 RSS 超过 512 MiB 时终止整个后端进程组,退出码为 125
pack build --no-version-prompt --max-rss 512
PACK_MAX_RSS=512 pack build --no-version-prompt
# 产物大小门禁,超过预算返回退出码 1,JSON 含 passed/violations
pack analyze --out-dir dist --top 20 --max-bytes 1048576 --max-file-bytes 262144 --json--profile:每次 tsup/tsdown 执行会打印 elapsed wall-clock 毫秒数;在 Linux 使用/proc对子进程树 RSS 约每 200ms 采样。数据不代表打包器内部的 transform/bundle/write 阶段耗时,也不是精确的内存高水位。其他操作系统可输出耗时,但 RSS 显示unavailable。--max-rss <MiB>:默认0(关闭),仅支持 Linux,合法范围 0–1048576。RSS 是各进程驻留页之和,共享页可能重复计算;瞬时内存尖峰可能在采样间隔内发生,因此它不是 cgroup/容器级硬限制。无法可靠采样时采用保守失败方式,资源超限退出码125,普通超时仍为124。禁止与--watch组合使用。- 进程树发现优先使用 Linux task children 接口;受限容器中若该接口不可用,则按
/proc进程 PPid 关系遍历(最多 20,000 个进程、512 个进程树节点)。监控是显式选择的,未启用时没有进程内存扫描开销。 --top取值 1–100,--max-bytes和--max-file-bytes为不超过 JS 安全整数的非负字节数。指定预算后,空产物目录判为不通过。产物门禁只检查发布目录现有文件,不重新构建,也不计算 gzip/brotli 压缩体积。- 开启 profile 或 RSS 预算时跳过 v4 增量缓存,以免因缓存命中绕过真正的资源测量。预算执行仍受原有包级构建锁保护。内存超限后的重试与 tsdown 自动回退被抑制,避免重复触发 OOM。
--profile/--max-rss不支持 watch 中的单轮资源控制;真实 tsup/tsdown 测试仍需要完整工作区依赖。新增测试src/build/round6.test.ts,CLI 冒烟验证了预算退出码和内存中断。
@composy/pack
LDesign 统一的 tsup 构建工作流工具包。
第五轮:中断恢复、产物体积分析与构建超时(2026-10)
本轮对上一轮显式启用的目录事务增加持久化 transaction.json。写入 staging、committing、committed、rolling-back、finalizing 等阶段;当进程被强制结束时,在取得包级锁并确认恢复目标后可保守恢复或清理。
# 只对调用 beginBuildOutputTransaction() 创建、带有效 journal 的事务生效
pack recover --out-dir dist
pack recover --out-dir dist --json
# 只读分析已有构建产物,无需启动 tsup/tsdown
pack analyze --out-dir dist
pack analyze --out-dir dist --json
# 对每一次后端执行限定最长 30 秒,默认 0(不限时)
pack build --no-version-prompt --timeout 30000
PACK_BACKEND_TIMEOUT=30000 pack build --no-version-promptpack recover 使用与 pack build 相同的包级构建锁,拒绝 src、.cache、.git 等受保护路径、符号链接和不确定的恢复状态。它绝不推测没有 journal 的临时目录属于自己;文件状态不一致时明确报错,保留文件供人工处理。程序化调用者也必须协调同一个锁,避免在仍活跃的 staging 会话上执行恢复。
pack analyze 仅报告已存在目录的总字节数、文件数、扩展名分布和最大的 10 个文件;不宣称能测得构建阶段耗时或子进程峰值内存。--timeout 是每次后端进程的墙钟时间限制,0 为禁用,最大 86,400,000 毫秒;超时返回退出码 124,在类 Unix 系统尽力终止其进程组并保留锁直至强制终止宽限期结束;不能与 --watch 同时使用。Windows 后代进程清理仍需要真实 Windows CI 验证。
仍需注意: 本 API 并未自动接入任意 tsup/tsdown 配置。journal 不是读者可见的原子目录交换;SIGKILL 中断后的可辨识状态已测试,但断电、磁盘写入丢失、跨主机共享盘一致性和文件系统损坏不保证恢复。请在完整仓库内运行真实双后端构建、官方 Vitest、ESLint 和发布检查。
新增回归位于 src/build/round5.test.ts,详细限制、测试记录和逐文件修改见 tools-tsup-config-第五轮深度优化与验证.md。
第四轮:可验证增量缓存与构建目录事务(2026-10)
显式增量缓存(CLI 已接入)
# 必须明确声明构建依赖和最终产物目录;可重复添加 --cache-input
pack build --no-version-prompt --cache --cache-input src --cache-input tsconfig.json --cache-output dist
# 自动配置、版本提示、并发锁与 JSON 计划仍保持原有功能
pack build --cache --cache-input src --cache-output dist --dry-run --json- 默认关闭,只有显式
--cache才跳过构建。必须提供至少一个--cache-input和--cache-output。指定的源文件/目录、构建配置文件、package.json、选定后端可执行文件、CLI 自身、环境变量及输出目录按 SHA-256 内容参与校验;不依赖mtime,不存在仅因时间戳未变而错误命中的情况。 - 命中要求上一次成功构建的输入哈希、输出哈希都一致,并且输出非空。文件增加、删除、修改、变更执行权限、符号链接和特殊文件都会触发失效或显式报错。缓存保存使用临时文件与同目录替换;构建过程中输入发生变化则拒绝保存缓存。
- 遇到 watch、可能升级版本的构建、串行配置、清理/强制操作,以及启用自动回退的 tsdown,会保守地绕过缓存。进程级互斥继续由前一轮构建锁实现。
- 使用者必须声明完整依赖:例如
tsconfig、额外配置、自动生成代码、代码生成参数、插件配置和 workspace 锁文件。缓存不能推断动态 import、任意插件访问、网络数据、未在包目录内的 monorepo 文件或外部服务变化。如果依赖无法完整声明,不要开启缓存。 - 缓存是“验证过的跳过执行”,不是远端/离线产物恢复仓库。首次执行会发生全量哈希 I/O;对于体积巨大的构建产物,哈希时间可能高于执行时间,不承诺任意项目都有速度提升。
完整输出目录事务(程序化 API,未自动接入任意 CLI 配置)
import { beginBuildOutputTransaction } from '@composy/pack/build/outputTransaction'
const transaction = beginBuildOutputTransaction({ packageRoot: process.cwd(), outDir: 'dist' })
try {
// 调用方必须把实际打包器的输出目录设置为 transaction.stagingDir。
await runMyBundler({ outDir: transaction.stagingDir })
transaction.commit()
await verifyMyPublishedOutputs()
transaction.finalize()
}
catch (error) {
transaction.rollback()
transaction.dispose()
throw error
}这组 API 将新构建写到独立临时目录,检查非空、符号链接和特殊文件;发布时将旧目录移入备份并替换为新目录。发布后验证失败可执行 rollback() 恢复旧目录;验证完成后执行 finalize() 清理备份。严禁指定 src/、bin/、.git/、.cache/、packages/ 等受保护的工程目录。直接使用 pack build 不会自动启用此 API,因为任意 tsup/tsdown 配置的 outDir、多配置和 onSuccess 回调尚无法安全强制重定向。
原子性边界: 同一磁盘的 rename 减少部分写入,但目录替换由多步操作构成,其他无锁读取者可能看到短暂空缺;SIGKILL、断电和多宿主共享盘的崩溃恢复仍未实现。必须在构建时持有包级锁并保证没有别的进程写同一目录,不能把它宣传为崩溃原子的事务提交。
新增测试文件 src/build/round4.test.ts;完整逐文件说明在 tools-tsup-config-第四轮深度优化与验证.md。
配置与目录结构
本包的权威工程配置集中在 .ldesign/:pack.config.ts 定义自身构建,eslint.config.js、
tsconfig.json 和 tsconfig.typecheck.json 分别维护 lint、构建类型与独立类型检查设置。
根目录保留的同名 ESLint/TypeScript 文件供 CLI、编辑器和既有脚本自动发现;TypeScript 入口只补充
包根相对的 rootDir 路径锚点,权威规则仍由 .ldesign/ 维护。源码仍位于 src/,不因配置归档改变源码布局。
它不是单纯的一组 preset,而是一套围绕包构建的完整能力集合:
- 统一的
tsuppreset - 可直接调用的
packCLI - 无配置自动构建,常规
tools/*包不再必须维护.ldesign/pack.config.ts - 外部依赖、banner、输出扩展名等构建细节工具
src多入口自动收集,避免每个工具包重复写递归扫描脚本- 构建后的复制、manifest、摘要与 Top Files
- package.json 声明产物校验,防止
exports/bin指向不存在文件 - 面向 monorepo 的诊断与排障能力
为什么需要它
在多包仓库里,最常见的问题不是“不会打包”,而是“每个包都在重复写、重复改、重复排查”:
- 每个包都维护一份高度相似的
tsup配置 external、banner、shebang、outExtension策略容易逐步漂移- 构建完成后还要复制文件、生成清单、看产物体积
- 遇到
pnpm链接异常、.bin缺失、配置没找到时,排查路径长且重复
@composy/pack 的目标是把这些重复劳动统一抽到一处,并保持足够强的类型约束和可读性。
功能总览
1. 五个开箱即用的 preset
| preset | 适用场景 | 默认输出 | 关键特性 |
| ---------------------- | ---------------- | ------------- | ---------------------------------------------------- |
| defineLibraryConfig | 大多数通用库包 | esm + cjs | 平衡默认值、类型声明、统一 externals |
| defineNodeConfig | 纯 Node 运行时包 | esm + cjs | 默认 target 更现代,并跳过可选 .node 原生文件 |
| defineCliConfig | CLI 工具 | esm + cjs | 自动或显式识别 CLI 入口并注入 shebang |
| defineBrowserConfig | 浏览器包 | esm | 强制 platform: 'browser',可选浏览器框架 externals |
| defineAdvancedConfig | 复杂或多入口包 | 按配置决定 | 保留更多 tsup 原生控制能力 |
2. 统一构建基础设施
commonExternals、cliCommonExternals、browserCommonExternalsmergeExternals()makeVersionBanner()、mergeBanner()、shebangBanneroutExtensionJsCjsrunOnSuccessHook()runPostBuildTasks()collectSourceEntries()verifyPackageOutputs()BuildProgressTracker
3. 统一 CLI 工作流
pack 内置五类能力:
pack build:解析配置并转发参数给默认构建后端tsup;tsdown仅在显式选择时使用,只有可识别的后端启动/配置加载错误才自动回退tsup;源码编译失败直接报错pack init:快速生成.ldesign/pack.config.tspack inspect:查看最终解析到的包、配置与构建后端 CLI 路径pack explain:解释配置查找和零配置推断结果,不执行构建pack doctor:直接诊断配置缺失、构建后端链接异常和.bin问题
执行日志
每次 pack 命令都会在目标项目下创建完整执行日志:
.ldesign/.logs/pack/<ISO 时间>-<pid>.log日志包含命令行、运行环境、构建后端输出、stderr、异常堆栈、退出码与耗时。常见的 token、密码、secret 与 API
key 参数会自动脱敏;日志目录不可写时不会改变构建结果。pack run --tool <name>
会把指定命令及其全部子进程输出写入
.ldesign/.logs/<name>/,适用于声明生成、webview 编译等多阶段构建。
pack verify:检查main、module、types、bin与exports声明的文件是否存在
4. 统一产物整理
所有 preset 都能直接复用:
- 构建后复制文件与目录
- 生成 manifest
- 打印构建摘要与 Top Files
- 在非交互终端中自动退化输出
当前版本重点改进
这一版围绕“正确性、默认值一致性、可维护性”做了进一步收敛:
- 修复
mergeBanner()在函数 banner 场景下使用伪上下文的问题 - 显式
packageRoot/callerDir现在会优先于npm_package_json - CLI shebang 注入改为按包根目录解析输出路径,避免多包仓库下写错位置
- preset 不再粗暴覆盖显式
sourcemap/minify配置 - Node 内置模块 externals 规则改为基于
builtinModules动态生成,覆盖子路径导入 - 浏览器框架 externals 现在能识别
react/jsx-runtime、react-dom/client等常见子路径 - post-build 复制新增安全校验,避免把目录复制进自身子目录
- 新增
collectSourceEntries(),用于统一构建src下所有运行时 TypeScript 文件 pack build支持无配置自动推断:优先使用显式配置,没有配置时根据package.json与src生成临时 tsup config- 新增
pack verify/verifyPackageOutputs(),用于校验 package.json 声明产物 - 零配置构建现在会从
package.json的main/module/exports/bin推断format与输出目录,并从engines.node推断更合适的 Node target pack verify --strict可把“未声明任何发布产物”升级为失败;声明路径逃出包根或指向目录也会失败- 新增基于
dist/的本地自检脚本,能对关键行为做回归验证 - CLI 源码入口收敛为
src/bin/pack.ts,库入口构建显式排除src/bin pack build新增--retry <count>与PACK_RETRY_ATTEMPTS,用于重试 Windows 环境里偶发的spawn EPERM- package output 通配校验现在会缓存扫描目录,减少多条
exports通配声明带来的重复 I/O - 控制台输出改为稳定的 key/value 面板、Top Files 摘要和 TTY/非 TTY 兼容样式
安装
pnpm add -D @composy/pack tsup如果你在 monorepo 中使用 workspace 依赖,也可以直接这样写:
{
"devDependencies": {
"@composy/pack": "workspace:*"
}
}要求:
- Node.js >= 18
- 推荐在
type: module项目中使用 - 非 ESM 项目同样可使用,只要
tsup配置和入口定义正确
30 秒快速开始
1. 添加脚本
{
"scripts": {
"build": "pack build",
"dev": "pack build --watch"
}
}2. 执行构建
pnpm run build常规工具包可以不写 .ldesign/pack.config.ts。pack build 会先查找显式配置;没有配置时,会根据
package.json、src/index.ts、src/**/*.ts、src/**/*.d.ts 和 package.json#bin
自动生成临时配置。默认仍输出 esm、cjs 和 d.ts 到 dist;如果 package.json 已经声明了
module、main、exports 或非 dist 输出目录,自动配置会优先贴合这些发布声明。其中
src/**/*.d.ts 只参与声明生成上下文,不会被当作 JS 运行时入口打包。
3. 只有特殊需求才创建配置
需要自定义 copy、external、platform、tsconfig、webview 构建或非 src 布局时,再生成配置:
pack init --template libraryCLI 说明
pack build
普通交互终端在构建前会询问是否升级当前包版本。确认后可选择
patch、minor、major、预发布通道或输入完整 semver;构建成功后,当前 workspace 中依赖该包的子包会同步依赖版本,匹配的 pnpm
catalog 与 lockfile 也会更新,并在当前包目录生成详细的
CHANGELOG.md。日志包含版本前后值、每个 workspace 消费方的依赖字段变更、catalog/lockfile 状态,以及 Git 提交分类、作者、提交哈希、Breaking
Changes 和统计信息。构建、同步或日志写入失败时会恢复版本文件和已修改的 workspace 文件。
只有实际升级版本时才生成日志;未升级版本、--dry-run 和 --watch 不会写入
CHANGELOG.md。没有 Git 历史时会保留完整的版本事务摘要。
CI、脚本和其他非 TTY 环境不会阻塞询问;需要升级时显式传入
--version-bump patch|minor|major|alpha|beta|rc|<semver>,也可以使用 PACK_VERSION_BUMP。可用
--no-version-prompt、--no-workspace-update、--no-lockfile-update 关闭对应行为;子模块场景可用
--workspace-root <path|auto|local> 控制 workspace 边界。
自动向上查找配置文件;找不到配置时自动推断一份临时 tsup config,并把剩余参数透传给 tsup:
pack build
pack build --watch
pack build --minify
pack build --print-config
pack build --dry-run
pack build --retry 5--dry-run 会完成配置解析和零配置推断,并输出实际会使用的配置路径;配合 --json
可用于 CI 或批量迁移脚本确认构建计划,但不会启动 tsup,也不会写入 dist。
零配置推断会尽量遵循 package.json:
module、exports.import会启用esmmain、exports.require会启用cjsmain/module/types/exports指向build/*这类目录时,outDir会跟随声明目录engines.node为>=20或>=22时,target 会提升到node20或node22
--retry <count> 只针对瞬时 spawn EPERM 这类子进程启动失败生效。默认值在 Windows 上为
3,其他平台为 1;也可以通过 PACK_RETRY_ATTEMPTS=5 统一设置。
配置文件查找顺序:
.ldesign/pack.config.ts.ldesign/pack.config.js.ldesign/pack.config.mjspack.config.tspack.config.jspack.config.mjs.ldesign/tsup.config.ts(兼容旧项目).ldesign/tsup.config.js(兼容旧项目).ldesign/tsup.config.mjs(兼容旧项目)tsup.config.ts(兼容旧项目)tsup.config.js(兼容旧项目)tsup.config.mjs(兼容旧项目)- 无配置时,根据当前包自动生成临时配置
pack init
快速生成标准模板:
pack init --template library
pack init --template cli --entry src/cli.ts
pack init --template browser --out-dir build
pack init --template advanced --force支持模板:
libraryclinodebrowseradvanced
pack inspect
输出当前解析结果:
pack inspect
pack inspect --json
pack inspect --cwd packages/core
pack inspect --config tsup.config.ts输出信息包括:
- 当前工作目录
- 最近解析到的包名与
package.json - 实际使用的配置文件
- 配置来源:
explicit、discovered或auto tsupCLI 入口路径
pack explain
解释当前工作目录会如何解析构建配置,适合在大批量迁移到零配置 pack build 前做预检:
pack explain
pack explain --json
pack explain --cwd tools/runtime
pack explain --config .ldesign/pack.config.ts当没有显式配置时,它会展示自动推断出来的库入口、CLI 入口、本地声明补充文件数量、输出格式、target 与 d.ts 设置;当存在显式配置时,它会明确标出配置来源,避免误以为正在走零配置路径。
pack doctor
用于快速定位“为什么当前包跑不起来”:
pack doctor
pack doctor --json检查项包括:
- 最近的
package.json - 可解析的 tsup 配置,或可推断的自动配置计划
tsup/package.json是否可解析node_modules/.bin/tsup是否存在
在 pnpm workspace 里,如果 .bin 丢失,它会直接提示优先重建链接,而不是建议你先改脚本规避。
pack verify
用于在构建完成后校验 package.json 声明的产物路径:
pack verify
pack verify --json
pack verify --strict它会检查:
main/module/types/typingsbinexports中的相对路径,包含./dist/build/*.js这类通配路径
通配路径遵循文件系统 glob 的目录边界:单层 * 只匹配当前目录中的字符,递归
** 可以跨越零层或多层目录。例如 ./dist/**/*.d.ts 同时支持
dist/index.d.ts 与 dist/types/index.d.ts;这能覆盖多层 exports 构建产物,
又不会让 ./dist/*.js 意外匹配到更深层目录。
缺失任意声明产物、声明路径逃出包根或声明路径指向目录时,命令会以非 0 状态退出,适合接在 build
后面作为发布前保护。默认情况下,未声明任何产物只会给出 warning;如果 CI 需要强制发布包必须声明
main/module/types/bin/exports,使用 pack verify --strict。
pack run
将一个多阶段命令包装为单份完整工具日志。命令字符串应放在 -- 后,以便 shell 负责阶段串联:
pack run --tool launcher -- "pnpm run build:raw && pnpm run build:types && pnpm run build:verify"该命令会实时转发 stdout 和 stderr,记录每个阶段的完整输出与最终退出码;它不会改变原命令的执行目录或返回码。
Preset 详解
defineLibraryConfig
最适合大多数通用库包。
import { defineLibraryConfig } from '@composy/pack'
export default defineLibraryConfig({
entry: ['src/index.ts'],
manifest: true,
})默认行为:
format: ['esm', 'cjs']target: 'node18'dts: trueclean: truesourcemap在开发环境默认开启minify默认关闭
defineNodeConfig
面向 Node 运行时工具库或服务端包。
import { defineNodeConfig } from '@composy/pack'
export default defineNodeConfig({
copy: ['README.md'],
entry: ['src/index.ts'],
target: 'es2022',
})额外特点:
- 默认 target 更现代
- 会跳过某些可选
.node原生文件,降低跨平台构建失败概率
defineCliConfig
适合单入口或多入口 CLI。
import { defineCliConfig } from '@composy/pack'
export default defineCliConfig({
cliEntry: 'pack',
entry: {
index: 'src/index.ts',
pack: 'src/cli.ts',
},
})CLI preset 会额外处理:
- 自动或显式识别 CLI 入口
- 为对应 JS 产物注入
#!/usr/bin/env node - 当多入口又未明确指定
cliEntry时,在摘要中给出 warning
defineBrowserConfig
适合浏览器端 SDK、工具包或轻量 runtime。
import { defineBrowserConfig } from '@composy/pack'
export default defineBrowserConfig({
entry: ['src/index.ts'],
useBrowserExternals: true,
})特点:
- 默认只输出
esm - 强制
platform: 'browser' shims: false- 生产环境默认压缩
defineAdvancedConfig
适用于多入口、多平台或需要更细粒度覆盖 tsup 选项的场景。
import { defineAdvancedConfig } from '@composy/pack'
export default defineAdvancedConfig({
entry: {
index: 'src/index.ts',
runtime: 'src/runtime.ts',
},
format: ['esm', 'cjs'],
platform: 'node',
summary: {
artifactLimit: 6,
topFiles: 12,
},
})高级 preset 不是为了隐藏 tsup,而是为了在保留 pack 统一体验的前提下,给你更多底层控制能力。
共享能力
构建后复制与 manifest
import { defineLibraryConfig } from '@composy/pack'
export default defineLibraryConfig({
copy: [
'README.md',
{
from: 'assets',
to: 'assets',
},
{
from: 'CHANGELOG.md',
required: false,
},
],
manifest: {
extra: {
owner: 'platform-team',
},
fileName: '.ldesign-build.json',
},
})copy 支持:
- 字符串简写
- 文件与目录复制
- 自定义目标路径
required: false的软依赖文件
manifest 记录:
- 包名、版本、模式
- 输出目录
- 构建耗时
- 文件统计
- 全部输出文件
- 已复制产物列表
externals 复用
import { commonExternals, defineLibraryConfig, mergeExternals } from '@composy/pack'
export default defineLibraryConfig({
external: mergeExternals(commonExternals, ['typescript']),
})可直接复用:
commonExternalscliCommonExternalsbrowserCommonExternalsbrowserFrameworkExternalsmergeExternals
banner 与输出扩展名策略
import {
defineLibraryConfig,
makeVersionBanner,
mergeBanner,
outExtensionJsCjs,
} from '@composy/pack'
export default defineLibraryConfig({
banner: mergeBanner(
{ js: makeVersionBanner('@demo/core', '1.0.0') },
{ js: '/** custom banner */' }
),
outExtension: outExtensionJsCjs,
})进度与摘要
import { defineAdvancedConfig } from '@composy/pack'
export default defineAdvancedConfig({
progress: {
showCurrentFile: true,
throttleMs: 100,
},
summary: {
artifactLimit: 5,
topFiles: 10,
},
})progress 支持:
false关闭动态进度throttleMs控制刷新频率showCurrentFile控制是否展示当前处理文件
summary 支持:
false关闭最终摘要topFiles控制 Top Files 数量artifactLimit控制复制产物预览条数showArtifacts与showNotices控制展示细节
包自身的构建与验证
本包自身通过 .ldesign/pack.config.ts 构建。
构建策略:
src/**/*.ts会作为库入口参与构建src/**/*.test.ts与src/**/*.spec.ts会被显式排除src/bin/pack.ts由 CLI preset 单独构建到dist/bin/pack.js- 最终同时产出
esm、cjs与d.ts
常用命令:
pnpm run type-check
pnpm run lint:check
pnpm run build
pnpm run test
pnpm run test:run
pnpm run verify说明:
build会生成当前包的esm、cjs与d.ts产物build结束后会自动执行pack verify,确保 package.json 声明的产物全部存在test与test:run都会对当前dist/产物执行自检;如果未先构建,会直接给出提示quality:check/verify串联 ESLint、类型检查、构建、package 产物校验与 dist 自检format:check保留为独立格式检查,不阻断发布产物验证链路
类型导出
你可以直接复用以下类型:
LibraryConfigOverridesNodeConfigOverridesCliConfigOverridesBrowserConfigOverridesAdvancedConfigOverridesSharedPresetOverridesExternalMatcherTsupPluginBuildManifestBuildManifestOptionsPostBuildTasksResultProgressTrackerOptionsBuildSummaryOptions
更底层的封装能力也有导出:
createPresetRuntimePresetRuntimePresetDisplayMetaPresetOnSuccessContextWrapOnSuccessOptions
深度导入
默认推荐从根入口导入:
import { defineLibraryConfig } from '@composy/pack'如果你确实需要深度导入,也支持:
import { commonExternals } from '@composy/pack/build/external'
import { printBuildSummary } from '@composy/pack/log/logger'
import { defineCliConfig } from '@composy/pack/preset/cli'从 @composy/tsup-config 迁移
迁移要点:
- 包名改为
@composy/pack - CLI 命令改为
pack - 旧的
ldesign-tsup工作流统一收敛到pack - CLI 产物入口改为
dist/bin/pack.js
示例:
- import { defineLibraryConfig } from '@composy/tsup-config'
+ import { defineLibraryConfig } from '@composy/pack'- ldesign-tsup build
+ pack build故障排查建议
- 先看
pack doctor,再动脚本 - 常规
tools/*包优先尝试零配置pack build - 只有存在特殊构建需求时,再把显式配置放到
.ldesign/pack.config.ts - 遇到
node_modules/.bin/tsup缺失时,优先重建pnpm链接 - 多入口 CLI 包请显式设置
cliEntry - Windows 沙箱或杀软环境偶发
spawn EPERM时,优先使用pack build --retry 5或设置PACK_RETRY_ATTEMPTS - 如果你显式传了
sourcemap或minify,preset 现在会保留你的配置,不再强制覆盖
License
MIT
通过 @composy/cli 统一接入
- 接入类型:
bin - 统一命令:
ldesign tsup - 命令别名:
tsup-config - 包内原生 bin:
pack
当前包通过独立 bin 接入,统一命令会转发到包自身 CLI。
pnpm add -D @composy/cli
ldesign tsup --help
ldesign tools run tsup-config --help2026-10-10 源码补全与增强说明
上传的归档中缺少整个
src/build/目录及.ldesign/核心配置。本次恢复这些模块,保留原有外部 API 和发布入口,但仍需在完整仓库安装依赖后复验 tsup、tsdown、Vitest 和 ESLint 的实际集成。
- 类型安全和构建兼容:恢复全部
src/build/*引用;新增可独立引导自身的.ldesign/pack.config.ts;恢复 TypeScript / ESLint 配置。ESM 扩展名根据消费包package.json.type在.js、.mjs间选择,CJS 固定使用.cjs。 - 可解释的零配置:自动收集源入口、排除测试与声明文件,对重名入口主动失败;根据
bin推断 CLI 入口,混合入口使用defineCliConfig并定向注入 shebang。通过explain查看evidence、warnings,而无需写入文件。 - 产物安全:
verifyPackageOutputs校验 main/module/types/bin/exports/browser 的产物路径;递归**与单层*分离;拒绝路径逃逸和符号链接。copy强制检查源/目标目录边界、拒绝递归复制。Manifest 原子替换、可选 SHA-256,并排除旧 Manifest 的自引用统计。 - 性能:源目录和产物扫描使用迭代栈;Manifest 文件哈希使用固定 64 KiB 缓冲区,不因单个大型产物而将其整体加载到内存。子进程日志判错缓存仅保存最近 64 KiB,终端仍完整转发。
- CLI 稳健性:
--后参数不再被 pack 消费;支持--key=value;数值参数拒绝非纯数字;inspect 在没有可选 tsdown 时保持可用;dry-run 不生成缓存配置;tsdown shim 在执行后清理。
可选 Manifest 哈希
import { defineLibraryConfig } from '@composy/pack'
export default defineLibraryConfig({
entry: ['src/index.ts'],
manifest: {
fileName: '.ldesign-build.json',
hashes: true,
extra: { product: 'composy' },
},
})CLI 零配置与扩展名
- 若包有
bin并且源目录有可明确匹配的src/bin/<name>.ts或src/cli/<name>.ts,自动配置启用 CLI 预设,并按入口应用 shebang。 - 未声明
"type": "module"的 Node 包,默认 ESM 输出为.mjs、类型声明为.d.mts;type=module时使用.js、.d.ts。请使package.jsonexports 与实际输出一致,然后执行pack verify --strict。 - 对输出目录做复制、Manifest 等变更时,推荐在 CI 中启用
pack verify --strict,避免发布引用损坏。
第二轮可靠性增强(2026-10)
- 复制事务:
runPostBuildTasks({ copy, manifest })会先在输出目录的同一文件系统上暂存所有待复制文件,覆盖旧产物前创建备份,后续复制/Manifest 失败会恢复已有文件;成功后清除暂存。此功能不能替代整个构建目录的崩溃原子提交,暂存阶段也需要额外磁盘空间。 - 安全路径:所有复制源、目标和
exports检查均拒绝不安全的路径与符号链接祖先,避免跟随链接进入非预期目录。冲突的复制目标会在修改输出目录之前被拒绝。 - 后端回退:
--backend tsdown仅在识别到启动、CLI/loader 不兼容等问题时才可能回退到 tsup。语法/类型/插件编译失败不会重试另一套打包器,避免浪费 CPU、内存和覆盖中间产物。使用--no-fallback可完全关闭。 - 串行配置:
--serial-configs N支持异步配置函数并在请求的下标不存在时抛错;与--watch同时使用时给出明确提示。此行为不等于整个配置数组的预验证。 - Manifest 完整性:扫描目录或读取文件元数据失败时,后处理会失败并撤销本轮复制,而不是静默生成缺失产物的 Manifest。大文件 SHA-256 继续使用固定大小缓冲区。
运行 pnpm run test:run 和 pnpm run typecheck 可在完整工作区验证;新增回归用例位于 src/build/round2.test.ts。双后端 ESM/CJS/DTS 的真实集成测试仍需在装有依赖的 CI 中执行。
第三轮:跨进程构建锁与严格发布产物验证(2026-10)
本轮新增的锁用于协调 通过 pack 启动的进程,不控制直接调用 tsup/tsdown 的其他工具,也不等同于完整构建目录的崩溃原子提交。
- 同包构建互斥:
pack build在任何版本文件修改前创建.cache/ldesign-pack/build.lock。同包的 watch 和普通构建不会同时写入相同输出目录。锁文件以独占创建和随机持有者标识实现,不按运行时间强制抢占仍存活的本机进程。 - 工作区版本修改互斥:可能执行版本升级时(显式
--version-bump或交互式版本确认),先取得工作区根目录的.cache/ldesign-pack/workspace-version.lock,再获取包级锁。防止不同子包通过pack同时更新同一组 workspacepackage.json、catalog 或 lockfile;不修改版本的不同子包仍能并行构建。 - 异常中断恢复:如果持有者本机 PID 已退出,经过短暂安全宽限期后可回收遗留锁;解析失败的陈旧锁也能在一定时间后恢复。远端机器上的锁不因时间过长而自动抢占,需运维人员确认并处理。
- 严格产物检查:用于生成 Manifest 的严格扫描现在会拒绝符号链接、设备和其他非普通文件,避免产物清单静默漏报。对已有 copy 事务,扫描失败时会回滚复制操作。
pack verify的 wildcard 扫描也不再把权限错误伪装成产物不存在。
# 默认最多等待 30 秒;如已有构建,可选择立即失败或延长等待
pack build --lock-timeout 0
pack build --lock-timeout 120000
PACK_LOCK_TIMEOUT=60000 pack build
# 只分析而不执行构建,也不会获取构建锁或生成临时配置
pack build --dry-run --json--lock-timeout 为毫秒,允许 0 至 600000。上述锁不覆盖进程被强制杀死时的整个 dist 回滚;也不能提供严格缓存命中、跨主机任意文件系统的一致性或替代 CI 中的真实双后端测试。新增回归用例见 src/build/round3.test.ts。
第七轮增强:事务构建、依赖调度、结构化报告
CLI 性能与生命周期日志
--report 是显式启用的构建执行报告,--event-log 是 JSONL 事件文件;两者不会修改原来的默认日志格式,也不会保存环境变量或后端 stdout/stderr。
pack build --no-version-prompt \
--report .cache/ldesign-pack/latest-report.json \
--event-log .cache/ldesign-pack/events.jsonl
pack report --json
pack report --file .cache/ldesign-pack/latest-report.json报告记录实际耗时、真实子进程退出码、缓存状态和后端尝试次数。Linux 上 RSS 仅在启用 --profile 或 --max-rss 时有采样数据;未采样使用 null,不会虚构内存值或编译各阶段耗时。--report 写入错误只发出警告,不会使已经成功的构建被误报为失败。诊断路径必须位于当前工作目录内,不能穿越符号链接。
事务式构建 API(显式接入)
import { runTransactionalBuild } from '@composy/pack/build/buildPipeline'
await runTransactionalBuild({
packageRoot: process.cwd(),
outDir: 'dist',
async build(stagingDir) {
// 在此执行你能够确保“所有产物仅写入 stagingDir”的打包任务。
// 此示例不默认修改任意第三方 tsup/tsdown 配置。
},
async verifyPublished(outputDir) {
// 可选:检查发布后的公共输出目录;失败会回滚到旧目录。
},
})执行过程取得包级跨进程锁,并使用持久化 journal。对已存在、尚未恢复的事务采取拒绝继续而非自动清理策略,需要运行 pack recover --out-dir dist。两次目录重命名不是内核原子的目录交换,极端崩溃和断电仍有恢复边界。任意自定义插件可能写出 stagingDir,因此不会在默认 pack build 上不加验证地启用事务。
Monorepo 依赖 DAG 调度 API
import { runBuildGraph } from '@composy/pack/build/buildGraph'
const result = await runBuildGraph([
{ name: 'core', dependencies: [] },
{ name: 'ui', dependencies: ['core'] },
{ name: 'docs', dependencies: ['core'] },
], {
concurrency: 2,
build: async (name) => { /* 调用各包已有的构建流程 */ },
})
// result.statuses: { core: 'success', ui: 'success', docs: 'success' }调度器会在执行前检查未知包、重复依赖与环,并在依赖失败时跳过下游节点,独立分支继续执行。build 回调负责实际构建与路径隔离;自第八轮起可通过 pack workspace 自动发现包并执行脚本;底层 DAG API 仍可独立使用。
类型化事件
import { createBuildEventHub, formatBuildEvent } from '@composy/pack/build/buildEvents'
const hub = createBuildEventHub(1000)
const unsubscribe = hub.on('*', event => console.log(formatBuildEvent(event, 'human')))
hub.emit('build:start', { backend: 'tsup' })
hub.emit('build:end', { status: 0 })
unsubscribe()事件格式化支持 human、json、github;GitHub 注释中的换行和百分号会被转义。该接口仅用于仪表与审计;监听器异常不会改变构建结果。pack build 的事件文件记录已知的生命周期事件,无法提供打包后端未暴露的内部阶段数据。
第八轮:Monorepo Workspace 构建调度
pack workspace 可以直接读取仓库的 pnpm-workspace.yaml 或根 package.json 的 workspaces,生成由本地 dependencies、devDependencies、optionalDependencies 构成的构建 DAG;不会自动执行构建。
# 在 workspace 根目录或任意子包目录查询真实构建顺序
pack workspace --json
# 选择单个包,自动附带所依赖的工作区包
pack workspace --filter @composy/core
# 依赖优先、最多同时运行 4 个 npm build 脚本
pack workspace --execute --concurrency 4
# 指定脚本和包;先查看计划,再执行
pack workspace --filter @composy/launcher --script build --execute --dry-run
pack workspace --filter @composy/launcher --script build --execute
# CI 使用 JSON 汇总,失败退出码为 1
pack workspace --execute --json行为约定:
- 只解析安全的 glob 子集:
*、**、!排除规则。暂不支持花括号、字符类和复杂 YAML 写法;遇到不支持的格式直接报错,不会静默漏扫。 - 相同工作区包名会报错;本地依赖循环会报错;显式
workspace:引用但在工作区内找不到目标也会报错。支持workspace:@scope/name@^别名与workspace:../path形式。 --filter支持多次指定精确包名,自动追加传递依赖。没有声明脚本的目标包按失败处理,依赖它的包会跳过;独立包继续运行。- 不扫描
node_modules、.git、.cache、dist等生成目录,不跟随符号链接。基于 glob 前缀裁剪目录,工作区目录和包数量受到保护性上限约束。 --execute通过各包目录的npm run <script>启动子进程(继承 Node/npm 启动环境);--json模式下子进程输出转向 stderr,标准输出保留为单个 JSON 结果;默认并行度为 2,最大 32。--dry-run在--execute模式下也只输出 DAG 计划,不运行 npm 脚本。这个调度器不具备受信任代码沙箱:脚本与插件仍拥有调用它们的用户权限。- 目前没有自动变更影响分析、分布式缓存、运行中子进程的硬取消,也没有将任意后端配置强制套入目录事务。优先在真实依赖工作区验证这些差异。
库 API 可使用 discoverWorkspaceGraph({ root, filter }) 和 findPackageWorkspaceRoot(start),随后将 graph.nodes 交给 runBuildGraph 的自定义回调。API 不会替调用者执行 npm 脚本或更改 package.json。
第九轮:Monorepo 可取消调度与逐包构建报告
pack workspace --execute 现在支持进程信号取消和准确的逐包构建遥测:
# 执行工作区构建,记录每个包的结果、执行时间与退出码
pack workspace --execute --concurrency 4 --workspace-report .cache/pack/workspace-report.json
# 标准输出保持可解析的 JSON,npm 输出转向标准错误流
pack workspace --execute --json --workspace-report .cache/pack/workspace-report.json- 收到
SIGINT(通常为 Ctrl+C)或SIGTERM后,不再调度新包;运行中的任务取消、尚未运行的节点标记为cancelled,且等待清理结束后再返回。CLI 分别返回 130 / 143。 - POSIX 系统下,每个 npm 命令处于独立的进程组。取消时先发送
SIGTERM,400 毫秒后发送SIGKILL清理仍存活的组成员。Windows 使用taskkill /T /F尝试清理进程树,能力随系统权限变化。 - 普通构建失败仍表现为
failed;依赖它的包表现为skipped,不依赖的包继续执行。取消与失败不会混淆。 --workspace-report只在workspace --execute下可用。JSON 报告使用安全的工作区相对路径、临时文件写入与原子重命名,禁止..与符号链接路径。- 逐包
elapsedMs是调度器测得的真实墙钟耗时;未运行的包为null。exitCode对正常退出的脚本保留实际进程退出码,因信号或启动错误失败的场景可为null。报告不伪造打包器内部阶段耗时、峰值 RSS 或 npm 插件元数据。 - 库调用方可使用
runBuildGraph(nodes, { signal, build(name, signal) })与executeWorkspaceBuild({ graph, signal, ... })。自定义回调必须自行响应取消信号;调度器不可能强制终止任意 JavaScript Promise。
安全边界: 进程组清理不能约束主动脱离进程组、脱离工作区或提升权限的孙进程;Windows 上的进程树清理属于尽力而为。正常构建仍不自动进行输出目录事务重定向。真实 tsup/tsdown 的完整集成仍需在已安装依赖的真实工作区验证。
第十轮:工作区 fail-fast、逐包超时与资源预算
默认的 pack workspace --execute 仍按依赖传播失败:失败包的下游被跳过,独立分支继续。新增以下显式策略:
# 一个包失败后停止派发,并请求终止其他正在执行的脚本
pack workspace --execute --concurrency 4 --fail-fast
# 每个包最多运行 5 分钟;0 表示不限制
pack workspace --execute --package-timeout 300000 \
--workspace-report .cache/pack/workspace-report.json
# Linux:采样 npm 进程及后代的 RSS;超出 512 MiB 后尝试终止
pack workspace --execute --workspace-max-rss 512 --json
# 组合策略。--dry-run 仍只显示依赖图,不执行构建
pack workspace --execute --concurrency 4 --fail-fast \
--package-timeout 300000 --workspace-max-rss 512行为与报告字段:
--fail-fast默认关闭;开启后首次失败保留failed及其原始报错,活动包收到取消信号,待运行包标记为cancelled。report.stopReason为fail-fast,而外部 SIGINT/SIGTERM 的原因是signal;正常完成是null。report.cancelled保留“是否收到外部取消信号”的原有含义。--package-timeout的单位是毫秒,合法范围为 0–86,400,000。超时包的status为failed,exitCode为124,timedOut: true。未开启 fail-fast 时,独立包继续,失败包的下游被skipped。--workspace-max-rss的单位是 MiB,最大为 1,048,576,仅支持可读取/proc的 Linux。确认超限:exitCode: 125、rssLimitExceeded: true;无法可靠采样:exitCode: 125、resourceCheckFailed: true,不会冒充已确认超限。已采样时记录sampledPeakRssBytes/rssSampleCount,否则不制造数据。- 这些选项只能用于
workspace --execute;--timeout和--max-rss仍专用于单包pack build。--dry-run从不启动 npm 脚本,--json的标准输出保留单份结构化结果。 - 报告采用原有 schema 1 并新增可选字段,可继续读取旧报告;写入时校验 2 MB 上限,与读取上限一致。npm 脚本及自定义 runner 仍以调用者身份运行,不具备隔离能力。
库 API:runBuildGraph(nodes, { failFast: true, build(name, signal) }) 和 executeWorkspaceBuild({ graph, failFast: true, packageTimeoutMs, packageMaxRssMiB })。自定义 runPackage 必须响应收到的 AbortSignal 并等待自己的子进程清理;调度器无法安全终止任意未合作的 Promise。
限制: RSS 为约 100ms 的周期采样,不是硬内存上限,瞬时峰值可能遗漏;具有脱离进程组能力的子进程不在普通进程组清理保证内。真实 tsup/tsdown 完整打包、Windows 进程树处理、正式 CI 发布仍应单独验证。
第十一轮:显式工作区安全续建(2026-10-10)
pack workspace 在 v11 增加可选的已完成包复用与中断续建检查点。默认关闭,不改变 v10 的构建或失败传播行为。
pack workspace --execute --concurrency 4 \
--resume-state .cache/pack/workspace-resume.json \
--resume-input src \
--resume-input build.cjs \
--resume-output dist \
--workspace-report .cache/pack/workspace-report.json注意:示例假定每个包都有 src、build.cjs,构建生成非空 dist 目录。实际项目应按自己的配置/插件/生成器补齐 --resume-input,例如 tsconfig.json、.ldesign/pack.config.ts 或其他影响输出的文件。包自身 package.json、工作区根 package.json 及现有的常见 lockfile/workspace 声明会自动参与指纹;Node 版本、平台、架构、工作区图、脚本、全部环境变量也参与校验。不自动枚举任意动态插件、远程输入或包外文件,输入声明不完整时不要启用。
- 脚本成功且发布目录非空后,按 SHA-256 保存输入和产物树指纹;每个包成功后立即将状态原子写入
.cache/pack,不等待所有包成功。 - 下次执行仅在历史结果有效且输入/产物均未改变时标记为
reused,不会再次运行 npm 脚本。依赖包在本轮真正重新执行后,其下游一律重新执行,即使下游文件哈希没有变化。 - 启动一个包之前先持久化删除其旧成功检查点;如果进程遭到
SIGKILL,未完成的包不会误作为已完成复用。修改输入/根 lockfile、破坏产物、修改脚本/工作区依赖图都会使相关记录失效。 - 检查点路径只能位于工作区的
.cache/pack/下,不能覆盖源码和 manifest。拒绝符号链接、不存在的声明输入、输出与输入/其他包路径重叠及空产物。通过跨进程build.lock协调同一工作区内同样启用续建的 pack 进程。 --execute --dry-run仍只预览,不创建检查点或执行 npm;--resume-state必须与--resume-input(可多次)和--resume-output同时使用。- 工作区报告继续使用 Schema 1,增加
status: "reused",此类任务没有执行耗时或实际退出码(均为null)。既有旧报告仍可解析。
边界条件: 这是已发布产物的验证后跳过执行,不是持久化产物仓库、分布式缓存、构建的全自动依赖分析或完整构建目录事务。工具无法阻止非协作脚本写入任意目录,也不能证明开发者声明了全部动态依赖;两个不使用同一协作锁的外部构建进程也可能冲突。正式 tsup/tsdown 打包、Windows CI、Vitest 和发布检查需要在真实依赖工作区进一步执行。
库 API 可使用 createWorkspaceResume({ graph, script, statePath, inputs, outputDir }) 后传入 executeWorkspaceBuild({ graph, resume, ... })。直接调用该 API 时必须由调用者持有工作区锁;CLI 会自动获取并在结束时释放。
