tsdown

tsdown

当工作涉及 tsdown 时使用此技能：库构建、tsdown.config、dts/exports、依赖外置、watch/unbundle、CSS/插件/工作区、从 0.22 升级到 0.23，或从 tsup 迁移。

快照：[email protected]（2026-10-01）。如果版本不同，请根据 source-map.md 刷新内容。

工作流

1. 检查本地 tsdown 配置：
   • 包版本（优先使用 [email protected]；此快照为 0.23.0）。运行此工具所需的 Node 版本：^22.18.0 || ^24.11.0 || >=26.0.0（0.23 中已不再支持 Node 25）。
   • 配置：tsdown.config.ts / package.json#tsdown；对等依赖（typescript、@tsdown/css、publint 等）。
   • package.json 中的 type、exports、types、engines.node（用于目标版本/dts 自动检测）。
   • 是否正在从 tsup 迁移（external、entryPoints、bundle: false 等）。
2. 日常使用方法请先参考 usage-guide.md。
3. 版本不一致时刷新文档。请从 source-map.md 开始。
4. 按需查阅更深入的细节：
   • 配置/CLI/默认值：config-cli.md。
   • dts、包 exports、依赖：dts-exports-deps.md。
   • 插件、CSS、复制、工作区、编程式用法：plugins-css-workspace.md。
   • tsup 迁移和从 0.22 升级到 0.23：migrate-from-tsup.md。
5. 优先使用当前 API：entry、deps.neverBundle / alwaysBundle / onlyBundle、unbundle、copy、cjsDefault、dts.generator。将 CJS 视为维护模式；新库优先采用纯 ESM。
6. 使用 bunx tsdown（或项目的 build）验证，检查 dist 和 exports/types，然后通过 smoke import 使用该包。

核心判断

• tsdown 是基于 Rolldown + Oxc 的库打包器，是 tsup 的精神继承者，而非应用打包器。
• 默认值与 tsup 不同：format: 'esm'、clean: true；dts 通常根据 package.json 的 types/exports 自动检测；target 根据 engines.node 确定。
• 优先使用 deps.neverBundle / alwaysBundle，而非已弃用的 external / noExternal（0.23 中仍接受这些选项；同时设置两种形式会报错）。
• 0.23 移除了与 tsup 兼容的选项（bundle、outExtension、publicDir、removeNodeProtocol、injectStyle、inlineOnly、skipNodeModulesBundle、deps.onlyAllowBundle、dts.cjsReexport）；这些选项会导致类型检查失败，并在运行时被忽略。
• 默认依赖策略：包的 dependencies/peers 会被外置；已使用的 devDependencies 可能会被打包——行为不符合预期时，使用 deps 覆盖。
• 生成 dts 需要安装 typescript。仅通过 dts.generator: 'oxc' | 'tsc' | 'tsgo' 选择生成器（省略时：若启用了 isolatedDeclarations，则使用 oxc；若安装了 TypeScript 7，则使用 tsgo；否则使用 tsc）。dts.oxc: true / dts.tsgo: true 不再用于选择生成器。
• 0.23 中 deps.resolveDepSubpath 默认值为 false——外置子路径会保持原样。
• build() 会返回一个句柄：const { bundles, watch } = await build(...)。
• 使用 @tsdown/css / @tsdown/exe 时，其版本必须与 tsdown 一致。
• 不支持 stub 模式——请使用 --watch 和/或 exports.devExports。
• 代码拆分始终开启——没有 splitting: false。
• 从 0.22 或 tsup 升级：先在 0.22.14 上构建一次，确保没有弃用警告，然后升级到 0.23（tsdown-migrate 在第一阶段会固定使用 0.22.14）。
• 命令示例优先使用 bun / bunx。

验证

优先使用仓库自有的命令。对于有意义的 tsdown 工作，覆盖相关子集：

• 运行 bunx tsdown --version，并确认 CLI 的 Node 引擎要求。
• 干净构建：运行 bunx tsdown / bun run build；检查 dist 中的格式和扩展名（.mjs/.cjs/.js）。
• 类型：从依赖包中使用 .d.ts / exports.types，或运行 tsc。
• 双格式：当 format 同时包含两种格式时，执行 require + import 冒烟测试。
• 使用 exports: true 后：如果已启用，通过 publint/attw 验证 package.json。
• 迁移：升级到 0.23 前，确保 0.22.14 没有弃用警告；升级后，不再有已移除的选项，且 attw 仍能通过（默认配置现在为 esm-only）。

说明运行了哪些检查、未运行哪些检查，以及仍存在哪些版本假设。