tsdown CLI 完整命令参考在 Airi 多包 Monorepo 中构建 30 库的实战指南【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi导读tsdown 是 Airi 项目内部大量 TypeScript 包使用的库级打包器基于 Rolldown/Oxc可在.agents/skills/tsdown/SKILL.md中查看其定位。本指南以 tsdown CLI 的完整参考文档为核心系统讲解每一个命令行参数的语义、映射规则与典型用法并结合 Airi 仓库内真实存在的tsdown.config.ts与 npm scripts 佐证其实际落地方式。读完本文你将能熟练用一行命令打出 ESM/CJS/类型声明、开启 watch 开发、注入环境变量、构建 Node 可执行文件并把 CLI 心智平滑迁移到配置文件编写。一、tsdown CLI 的心智模型在使用任何参数之前先建立两条核心认知CLI 与配置文件是同一套选项体系的两种入口。参考文档 reference-cli.md 明确指出所有 CLI flag 都可以写进配置文件Config File而 CLI flag 的优先级更高——CLI 参数会覆盖配置文件中的同名选项。tsdown 的构建期运行门槛是 Node.js 22.18.0但产物可以通过target/--target面向更低的 Node 运行时例如 Airi 仓库统一用target: node18因此库的使用者并不会被锁定在 Node 22详见 option-target.md。Airi 正是这一心智模型的规模化实践者仓库在 pnpm workspace 下散落着数十个tsdown.config.ts如packages/*、plugins/*、integrations/vscode/*、server/packages/*、services/computer-use-mcp并普遍在package.json中注册build: tsdown与dev: tsdown --watch脚本例如 integrations/vscode/vscode-airi/package.json 第 65-66 行。二、Flag 命名规律先掌握 4 条映射规则CLI 参数到配置对象的映射遵循固定规则记住它们就能反推出绝大多数写法CLI 写法等价配置--foofoo: true--no-foofoo: false--foo.barfoo: { bar: true }--format esm --format cjs重复传参format: [esm, cjs]同时CLI flag 同时支持 camelCase 与 kebab-case例如--outDir与--out-dir完全等价。这意味着一套参数存在--treeshake/--skip-node-modules-bundle点号多级键等多种书写组合使用时按团队习惯统一即可。三、基础命令与配置加载基础命令# 使用默认配置构建 tsdown # 直接指定入口文件构建 tsdown src/index.ts src/cli.ts # 以 watch 模式构建 tsdown --watch不带任何参数时tsdown 会读取约定位置的配置文件并执行一次性构建这一行为在 Airi 中被广泛使用例如各包中形如build: tsdown的脚本参见 packages/core-agent/package.json 第 36 行。--config, -c filename指定自定义配置文件tsdown --config build.config.ts tsdown -c custom-config.js当配置文件不在默认位置或需要多套配置如 release 专用配置时使用。配置文件支持的格式与加载细节可参考 option-config-file.md。--no-config跳过配置文件tsdown --no-config src/index.ts配合显式入口参数实现完全由命令行决定、不读取任何配置的纯净构建适合脚本化/临时验证场景。--config-loader loader选择配置加载器tsdown --config-loader unrun可选值auto默认自动探测、native使用 Node 原生加载、unrun使用独立的 unrun 加载器。在配置文件依赖特殊语法或遭遇加载冲突时切换。--tsconfig file指定 TypeScript 配置tsdown --tsconfig tsconfig.build.json默认使用项目根tsconfig.json当构建产物需要与源码解析配置如paths、编译目标解耦时可像示例一样指定tsconfig.build.json。四、入口点与输出产物[...files]位置参数即入口tsdown src/index.ts src/utils.ts入口文件可直接作为位置参数传入多入口、glob 模式与对象式入口{ index: src/index.ts }的完整说明见 option-entry.md。--format format输出模块格式tsdown --format esm tsdown --format esm --format cjs # 同时产出双格式支持esm、cjs、iife、umd。重复传参即多格式构建这也是三、Flag 命名规律中列表规则的典型体现。多格式与扩展名映射的细节见 option-output-format.md。--out-dir, -d dir输出目录tsdown --out-dir lib tsdown -d dist-d为短别名。Airi 中packages/server-runtime/tsdown.config.ts即使用outDir: dist。--dts生成 TypeScript 类型声明tsdown --dts对 TypeScript 库而言这是发行到 npm 的关键开关负责产出.d.ts。声明文件的 sourcemap、compilerOptions、Vue 支持等进阶配置见 option-dts.md。--clean构建前清理输出目录tsdown --clean避免上次构建的残留文件混入产物。Airi 中 packages/server-runtime/tsdown.config.ts 与 integrations/vscode/vscode-airi/tsdown.config.ts 均开启了该清理逻辑。五、构建优化目标、平台与产物瘦身--target targetJS 目标版本tsdown --target es2020 tsdown --target node18 tsdown --target chrome100 tsdown --no-target # 禁用一切语法降级转换接受 ECMAScript 版本es2020、Node 版本node18或浏览器内核版本chrome100三种粒度--no-target表示保留源码语法不做降级。这也是构建期 Node 22、产物可跑 Node 18的关键Airi 的多个 Node 侧包在 tsdown.config.ts 中统一书写target: node18例如 packages/cap-vite/tsdown.config.ts、packages/server-runtime/tsdown.config.ts、services/computer-use-mcp/tsdown.config.ts。--platform platform目标平台tsdown --platform node tsdown --platform browser可选node、browser、neutral平台中立不注入任何平台假设。平台决定内置变量的填充方式。在 Airi 中 packages/electron-screen-capture/tsdown.config.ts 通过多配置数组对同一入口分别以platform: node、platform: neutral、platform: browser产出三套构建是一包多平台的经典示范。--minify/--no-minify产物压缩开关tsdown --minify tsdown --no-minify布尔开关配置层面还支持dce-only仅做无用代码消除见 option-minification.md。--sourcemap生成 source maptsdown --sourcemap tsdown --sourcemap inline默认生成独立.map文件inline把 map 内联进产物。调试与线上排障场景可配合--watch使用Airi 多个库在配置中统一开启sourcemap: true如 packages/plugin-sdk/tsdown.config.ts、packages/plugin-protocol/tsdown.config.ts。--treeshake/--no-treeshakeTree Shakingtsdown --treeshake tsdown --no-treeshake布尔开关控制未使用代码的摇除更细粒度的自定义见 option-tree-shaking.md。六、依赖处理哪些进包、哪些外置--deps.never-bundle module强制外置tsdown --deps.never-bundle react --deps.never-bundle react-dom将模块标记为 external不打进产物由使用方自行安装。对 React 组件库、插件体系尤为重要——这正是点号嵌套键deps.neverBundle的 CLI 形态。Airi 中对 Electron/Vue 等宿主依赖的同类处理也可以在源码配置中看到例如 packages/electron-screen-capture/tsdown.config.ts 与 integrations/vscode/vscode-airi/tsdown.config.ts 中把electron、vue、vscode列为externalpackages/audio/tsdown.config.ts 也将 worklet worker 资源外置。--deps.skip-node-modules-bundle跳过所有 node_modulestsdown --deps.skip-node-modules-bundle不再解析与打包任何node_modules依赖适合产物以外部依赖为主、仅做源码转译的场景。依赖配置层面还支持alwaysBundle强制内联、onlyBundle白名单、自动 external 依赖/peerDependencies/optionalDependencies 等详见 option-dependencies.md。--shimsESM/CJS 兼容垫片tsdown --shims为跨模块系统运行时注入__dirname、__filename、import.meta.url等兼容垫片让同一份代码在 ESM 与 CJS 产物中行为一致详见 option-shims.md。七、开发工作流Watch、忽略与构建后钩子--watch, -w [path]监听构建tsdown --watch tsdown -w tsdown --watch src # 仅监听 src 目录-w为短别名可附带路径缩小监听范围。Airi 的 VSCode 插件开发即使用dev: tsdown --watch脚本integrations/vscode/vscode-airi/package.json。watch 的详细配置见 option-watch-mode.md。--ignore-watch path监听排除tsdown --watch --ignore-watch test配合 watch 排除测试目录、构建产物目录等高频变化路径避免无意义重编译。--on-success command构建成功后执行命令tsdown --watch --on-success echo Build complete!每次成功构建后执行的外部命令典型用于唤起下游测试、重启 demo server 或输出通知。八、编译期环境变量注入--env.* value注入单个变量tsdown --env.NODE_ENVproduction --env.API_URLhttps://api.example.com点号键会把NODE_ENV、API_URL编译进产物代码中通过import.meta.env.*或process.env.*访问。适合把构建时刻的版本号、时间戳等打进产物。--env-file file从文件批量加载tsdown --env-file .env.production从.env风格文件加载多组变量与--env.*可叠加使用。--env-prefix prefix按前缀过滤tsdown --env-file .env --env-prefix APP_ --env-prefix TSDOWN_默认前缀为TSDOWN_即只有以TSDOWN_开头的环境变量才会被构建器拾取可通过重复传参追加自定义前缀APP_、TSDOWN_同时生效把庞大的环境变量空间裁剪到白名单之内。九、静态资源拷贝与 Node 可执行文件--copy dir拷贝目录到产物tsdown --copy public tsdown --copy assets --copy static # 支持多目录将静态资源目录原样复制到输出目录。这在字体类/资源类库中非常常见Airi 的字体包便通过 unbundle external CSS 的方式分发静态资产参见 packages/font-departure-mono/tsdown.config.ts 等字体包配置。--exe打包为独立可执行文件实验特性tsdown --exe基于 Node.js 的 Single Executable ApplicationsSEA机制产出单文件可执行程序。使用前提与约束需要 Node.js 25.5.0Bun 与 Deno 下不受支持跨平台构建通过tsdown/exe支持开启后有一组默认行为变化默认格式切换为cjs除非 Node.js 25.7.0、默认关闭dts声明生成、禁止代码分割、仅支持单入口。tsdown src/cli.ts --exe更完整的配置项如多目标平台矩阵targets: [{ platform, arch, nodeVersion }]与跨平台构建说明见 option-exe.md。十、包管理增强exports 生成与发布前校验--exports自动生成 package.json exports 字段tsdown --exports根据入口与格式自动推导、回写exports字段让消费方按现代 Node 解析规则正确引用子路径。Airi 的 packages/electron-screen-capture/tsdown.config.ts 中exports: true与多格式、多平台组合出现。机制详见 option-package-exports.md。--publint包规范校验tsdown --publint运行 publint 校验 package.json 字段是否符合 npm 发布规范防患于发布前。--attwAre The Types Wrong 校验tsdown --attw检测类型声明.d.ts与exports映射是否在 ESM/CJS 双环境下都能被正确解析是 TypeScript 库发行的高价值检查。--unused未使用依赖检查tsdown --unused扫描声明依赖中未被实际引用的项。Airi 的插件包 plugins/airi-plugin-bilibili-laplace/tsdown.config.ts 即组合启用了dts、unused、publint可作为插件类库的发布配置范本。publint/attw 在 CI 中可通过ci-only值只在持续集成环境触发见 option-lint.md 与 advanced-ci.md。十一、日志、报告与调试--log-level level日志详略tsdown --log-level error tsdown --log-level warn四级可选silent、error、warn、info。CI 中建议error保持输出干净本地排障时info。--report/--no-report产物体积报告tsdown --no-report # 关闭体积报告默认开启 tsdown --report # 显式开启默认默认在构建结束时输出产物体积报告生产构建可用--no-report关闭。--debug [feat]调试日志tsdown --debug tsdown --debug rolldown # 仅调试指定特性--debug输出全量调试日志可附加特性名如rolldown做定向排查。十二、Vite 集成与 Workspace/Monorepo 能力--from-vite [vitest]复用 Vite 配置tsdown --from-vite # 读取 vite.config.* tsdown --from-vite vitest # 读取 vitest.config.*当项目已维护 Vite/Vitest 配置时可以让 tsdown 继承其中的解析与插件设定减少重复配置。Airi 每个包同时维护vite.config.ts/vitest.config.ts与tsdown.config.ts的做法恰好与此能力相呼应如 packages/plugin-sdk 的配置文件布局。--workspace, -W [dir]Monorepo 批量构建tsdown -W tsdown -W packages/进入 workspace 模式扫描并构建多个包可附带目录缩小扫描范围。对应配置文件的 workspace 用法见 option-config-file.md。--filter, -F pattern按包过滤tsdown -W -F my-package tsdown -W -F /^pkg-/ # 支持正则过滤目标包按配置名称或工作目录匹配正则模式用/.../包裹。例如在 Airi 的 monorepo 中可用tsdown -W -F /^airia/一类写法批量构建命名空间下的包。--unbundleBundleless免打包模式tsdown --unbundle保留源码目录结构、按文件转译输出而非合并成单包对需要子路径逐文件导出的工具库/组件库尤为合适。Airi 的多个包深用此模式packages/audio/tsdown.config.ts对象式多入口 unbundle: true、packages/i18n/tsdown.config.ts、字体包与electron-screen-capture的 browser 构型均开启unbundle。机制见 option-unbundle.md。--root dir输入根目录tsdown --root src tsdown --root .类似于 TypeScript 的rootDir决定入口文件路径到输出路径的映射关系进而控制产物目录结构。默认取所有入口的公共基础目录。详见 option-root.md。--fail-on-warn/--no-fail-on-warn警告即失败tsdown --no-fail-on-warn # 关闭默认开启默认情况下出现警告即构建失败--no-fail-on-warn可降级为仅警告不中断适合本地迭代时使用。配置层面还支持failOnWarn: ci-only仅在 CI 生效参见 option-log-level.md。十三、Airi 中的 CLI/配置实战组合以下是参考文档中Common Usage Patterns的完整汇总可直接替换为项目脚本每一条都能在 Airi 仓库找到同类落点# 1. 基础构建读配置一次成型 tsdown # 对应 Airi 各包 scripts.build如 integrations/vscode/vscode-airi/package.json 的 build: tsdown # 2. 库构建ESM CJS 类型 清理 tsdown --format esm --format cjs --dts --clean # 对应 packages/core-agent/tsdown.config.ts 的 entry 列表 dts 组合 # 3. 生产构建压缩 清理 关闭报告 tsdown --minify --clean --no-report # 4. 开发构建watch sourcemap tsdown --watch --sourcemap # 对应 integrations/vscode/vscode-airi/package.json 的 dev: tsdown --watch # 5. 浏览器 IIFE 包 tsdown --format iife --platform browser --minify # 6. Node.js CLI 工具 tsdown --format esm --platform node --shims # 7. 独立可执行文件 tsdown src/cli.ts --exe # 8. Monorepo 单包发布前置校验 tsdown --clean --dts --exports --publint # 对应 plugins/airi-plugin-bilibili-laplace/tsdown.config.ts 的 dts unused publint 思路 # 9. 注入环境变量构建 tsdown --env-file .env.production --env.BUILD_TIME$(date %s) # 10. 拷贝静态资源 tsdown --copy public --copy assets --clean值得强调的是CLI 与配置文件的选项一一对应因此上面任一组合都可写成defineConfig({...})。Airi 中 packages/electron-screen-capture/tsdown.config.ts 展示了更高阶的组织方式先定义sharedConfig再用defineConfig([...])输出数组对同一仓库生成 node / neutral / browser 三套构型并各自叠加entry、unbundle、platform等差异化字段。十四、Tips实战中直接可用的 8 条建议参考文档在末尾给出 8 条凝练建议此处逐条转述并标注原因复杂工程优先使用配置文件CLI 适合快速验证多入口、多格式、依赖矩阵请在tsdown.config.ts中沉淀。牢记 CLI 覆盖配置文件临时加--minify、--no-report等参数不会污染长期配置改动只对本次命令生效。多格式请链式传参--format esm --format cjs一次生成双格式满足 npm 同时提供 ESM/CJS 的现状。常开--clean避免旧产物残留导致发布内容与预期不符。TypeScript 库务必开--dts没有类型声明的库对 TS 使用方几乎不可用。开发期使用--watch配合--on-success可把测试/提示串进每次重编译后。善用--on-success做构建后任务例如自动跑冒烟测试或重启预览。开启--exports自动生成 package.json 字段减少手写exports/main/module的低级错误。十五、相关文档导航本文是 tsdown Skill 参考文档集的一部分继续深入可阅读同目录下的专题文档路径均已转为仓库根相对路径配置文件全解option-config-file.md入口点与 globoption-entry.md输出格式细节option-output-format.mdWatch 模式配置option-watch-mode.md独立可执行文件含跨平台矩阵option-exe.mdSkill 总览与最佳实践SKILL.md【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
