用途:当工作涉及 tsdown 时使用本技能,包括库构建、tsdown.config 配置、dts 与 exports、依赖外置、watch/unbundle、CSS/插件/工作区、0.22→0.23 升级或从 tsup 迁移。快照为 tsdown@0.23.0(2026-10-01),版本不同时从 source-map.md 刷新。
主要能力与判断:tsdown 是基于 Rolldown + Oxc 的库打包器,是 tsup 的精神继任者,不是应用打包器。默认与 tsup 不同:format 为 esm、clean 为 true,dts 常由 package.json 的 types/exports 自动推导,target 来自 engines.node。默认依赖策略:dependencies/peers 外置,被使用的 devDependencies 可能被打包,可用 deps 覆盖。优先用 deps.neverBundle / alwaysBundle / onlyBundle,而非已弃用的 external / noExternal(0.23 仍接受但两者同设会报错)。
使用方式:先检查本地 tsdown 表面——包版本(0.23.x 优先)、Node 版本(^22.18.0 || ^24.11.0 || >=26.0.0,0.23 移除 Node 25)、配置文件 tsdown.config.ts 或 package.json#tsdown、peer 依赖、package.json 的 type/exports/types/engines.node,以及是否从 tsup 迁移。日常操作先看 usage-guide.md;细节分别路由到 config-cli.md(配置/CLI/默认值)、dts-exports-deps.md(dts、exports、依赖)、plugins-css-workspace.md(插件、CSS、copy、工作区、编程式)、migrate-from-tsup.md(tsup 迁移与 0.22→0.23 升级)。
限制与注意:0.23 移除 tsup 兼容选项(bundle、outExtension、publicDir、removeNodeProtocol、injectStyle、inlineOnly、skipNodeModulesBundle、deps.onlyAllowBundle、dts.cjsReexport),它们会导致类型检查失败并在运行时被忽略。dts 需安装 typescript;生成器仅在 dts.generator 为 'oxc' | 'tsc' | 'tsgo' 时选定,省略时按条件选择;dts.oxc: true / dts.tsgo: true 不再选择生成器。deps.resolveDepSubpath 在 0.23 默认为 false。build() 返回句柄:const { bundles, watch } = await build(...)。使用 @tsdown/css / @tsdown/exe 时版本须与 tsdown 匹配。无 stub 模式,用 --watch 和/或 exports.devExports。代码分割始终开启。新库优先 ESM-only,CJS 视为维护。示例命令优先用 bun / bunx。验证应运行仓库自有命令,如 bunx tsdown --version、清理构建、检查 dts 与 exports、双格式冒烟、publint/attw 校验,并报告实际运行的检查项与未运行项。