AIRI 仓库中 tsdown 的底层配置：通过 inputOptions 与 outputOptions 直接透传 Rolldown 打包参数

本文围绕 AIRI 仓库中收录的 tsdown 高级参考文档 advanced-rolldown-options.md 展开，讲解如何利用 inputOptions / outputOptions 两个透传接口，把配置直接交给底层 Rolldown 打包引擎，实现 tsdown 未单独暴露选项的细粒度控制。读完后，你可以在多格式构建（ESM/CJS）场景下按格式差异化配置打包参数，理解仓库中 29 个 tsdown.config.ts 的通用配置模式，并知道何时应该优先使用 tsdown 自身选项而非绕过封装。

一、背景：tsdown 以 Rolldown 为核心打包引擎

tsdown 是一个基于 Rolldown（Rust 编写的高速打包器）与 Oxc 的 TypeScript/JavaScript 库打包工具。在 SKILL.md 中可以看到其定位与基本用法：

# 安装
pnpm add -D tsdown

# 基本用法
npx tsdown

# 指定配置文件
npx tsdown --config tsdown.config.ts

# 监听模式
npx tsdown --watch

tsdown 在其上层封装了 entry、format、dts、minify、deps 等语义化选项，但本质上这些选项最终都会转化为 Rolldown 的输入/输出参数。当 tsdown 没有暴露某个你需要的 Rolldown 选项时，就可以通过 inputOptions（对应 Rolldown 的 Input Options）和 outputOptions（对应 Rolldown 的 Output Options）两个接口直接干预底层行为。

AIRI 仓库实际使用的版本可以从 pnpm-workspace.yaml 的 catalog 与 pnpm-lock.yaml 中得到佐证：tsdown@^0.22.14，其解析到的依赖链中包含 rolldown@1.2.5，说明仓库构建确实运行在 Rolldown 之上。

警告：覆盖 Rolldown 选项前，应先熟悉 Rolldown 自身的配置语义。原文档明确要求参考 Rolldown 官方 Input Options 文档（rolldown.rs），因为透传的是引擎原生参数，其取值范围与默认值以 Rolldown 为准，而非 tsdown。

二、inputOptions：控制打包输入阶段

inputOptions 作用于打包的输入阶段，典型用途包括工作目录（cwd）、JSX 运行时配置、自定义解析行为等。文档给出了两种写法。

2.1 对象写法：静态合并

export default defineConfig({
  inputOptions: {
    cwd: './custom-directory',
  },
})

对象形式会与 tsdown 内部生成的默认输入选项合并，适合“一次性固定某几个参数”的场景。

2.2 函数写法：按输出格式动态修改

export default defineConfig({
  inputOptions(inputOptions, format) {
    inputOptions.cwd = './custom-directory'
    return inputOptions
  },
})

函数形式会接收 tsdown 已经构造好的 inputOptions 对象和当前构建的 format（如 'esm'、'cjs'），你可以在其中读改写任意字段后返回。当同一个包同时输出多种格式、且不同格式需要不同输入行为时，这种写法是必须的——因为对象写法对每个格式是同一份静态配置，而函数写法拿得到 format 上下文。

2.3 实战佐证：JSX 运行时透传

tsdown 技能文档中的 React 组件库示例演示了一个真实的 inputOptions 用途——为 React 组件库开启 JSX automatic runtime：

export default defineConfig({
  entry: ['src/index.tsx'],
  format: ['esm', 'cjs'],
  dts: true,
  deps: {
    neverBundle: ['react', 'react-dom'],
  },
  inputOptions: {
    jsx: { runtime: 'automatic' },
  },
})

这里 jsx: { runtime: 'automatic' } 是 Rolldown/Rollup 生态的输入侧 JSX 转换选项，tsdown 并未提供独立的 jsx 配置项，因此通过 inputOptions 透传正是文档所说的“tsdown 未暴露特定 Rolldown 选项”场景。

三、outputOptions：控制打包输出阶段

outputOptions 作用于打包的输出阶段，影响产物形态，如法律声明注释（legalComments）、代码分割、输出文件名等。

3.1 对象写法

export default defineConfig({
  outputOptions: {
    legalComments: 'inline',
  },
})

3.2 函数写法：区分 ESM 与 CJS

export default defineConfig({
  outputOptions(outputOptions, format) {
    if (format === 'esm') {
      outputOptions.legalComments = 'inline'
    }
    return outputOptions
  },
})

与 inputOptions 一样，函数形式收到的是 tsdown 预构造好的 outputOptions 对象与当前 format。上例的效果是：只有 ESM 产物的 JS 源码头部内联第三方 license 注释，而 CJS 产物维持 tsdown 默认的 legal comments 处理（通常抽取到 LICENSE.txt 或剥离）。

四、常见使用场景（完整继承原文档示例）

4.1 保留法律声明注释（Preserve Legal Comments）

部分开源库要求在分发产物中保留 license 注释。tsdown 默认可能将其抽取或剥离，透传 legalComments: 'inline' 可强制内联：

export default defineConfig({
  entry: ['src/index.ts'],
  outputOptions: {
    legalComments: 'inline',
  },
})

4.2 自定义工作目录（Custom Working Directory）

在 monorepo 中通过 workspace 或共享配置构建子包时，可能需要显式指定 Rolldown 的 cwd，让相对路径的解析与资源定位落在目标包目录：

export default defineConfig({
  entry: ['src/index.ts'],
  inputOptions: {
    cwd: './packages/my-lib',
  },
})

4.3 按格式差异化配置（Format-Specific Options）

多格式构建（format: ['esm', 'cjs']）是最典型的透传场景，函数写法让 ESM 与 CJS 产物可以使用不同的输出选项：

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['esm', 'cjs'],
  outputOptions(outputOptions, format) {
    if (format === 'esm') {
      outputOptions.legalComments = 'inline'
    }
    return outputOptions
  },
})

五、何时使用透传选项

文档给出的适用判据可以归纳为三条：

• 需要某个 tsdown 没有显式暴露的 Rolldown 选项（如 jsx、cwd、legalComments 的精细控制）；
• 同一构建需要按 format 做差异化（ESM 与 CJS 行为不同）；
• 其他高级打包场景。

同时文档强调了一条反模式提醒：能用 tsdown 自身选项就不要透传。例如压缩应使用 tsdown 的 minify 选项，而不是通过 outputOptions 去设置 Rolldown 的 minify 字段——tsdown 的 minify 内部封装了 Oxc 压缩与 CJS 兼容处理，绕过封装会丢失这些行为。

AIRI 仓库中 29 个包的 tsdown.config.ts 恰好印证了这条原则：绝大多数配置只使用 tsdown 层选项，例如 packages/better-ws/tsdown.config.ts 用对象形式 entry 定义多个子入口（index、client/crossws、server、server/h3）并开启 dts: true；services/computer-use-mcp/tsdown.config.ts 通过 target: 'node18' 声明运行时兼容目标而非手动调低压缩目标；plugins/airi-plugin-claude-code/tsdown.config.ts 则演示了 defineConfig 接受数组、一次声明多份配置的用法。只有当这些高层选项都不满足时才轮到 inputOptions / outputOptions 出场。

六、与仓库中其他 tsdown 配置模式的对照

为帮助定位 inputOptions / outputOptions 在整个配置体系中的位置，以下是 SKILL.md 与仓库实际配置中常见的相邻能力：

配置维度	tsdown 层选项示例	仓库实例
入口	entry 支持字符串数组或对象映射	packages/i18n/tsdown.config.ts（4 个 locales 子入口）
目标环境	target: 'node18'	services/computer-use-mcp/tsdown.config.ts
依赖处理	deps: { neverBundle } / inlineOnly	plugins/airi-plugin-claude-code/tsdown.config.ts
结构保留	unbundle: true + copy	packages/i18n/tsdown.config.ts
插件透传	plugins: [Yaml()]	同上（unplugin-yaml/rolldown）
底层透传	inputOptions / outputOptions	本文主题

可以看到，inputOptions / outputOptions 与 plugins 共同构成了“绕过 tsdown 高层语义、直接触达 Rolldown 引擎”的两条通道：插件解决“增加能力”，透传选项解决“修改引擎参数”。

七、实践建议（继承原文档 Tips）

1. 先读 Rolldown 文档再覆盖：透传的是引擎原生参数，取值、默认值、与其他选项的交互关系以 Rolldown 官方 Input/Output Options 文档为准；
2. 格式差异化用函数写法：只要逻辑涉及 if (format === ...)，就应使用 inputOptions(fn) / outputOptions(fn) 而非静态对象；
3. 覆盖默认值后必须充分测试：透传绕过了 tsdown 的参数校验与组合逻辑，回归风险比改 tsdown 层选项更高；
4. 优先使用 tsdown 自身选项：如压缩用 minify 而不是经 outputOptions 设置底层压缩字段；只有确认 tsdown 无对应选项时才透传。

八、关联文档

原文档末尾还指向同目录下的三份参考文档，均位于 tsdown 技能参考目录，与透传选项配合使用：

• advanced-plugins.md：插件系统（Rolldown / Rollup / Unplugin 兼容）；
• advanced-hooks.md：生命周期钩子（build:before、build:done 等）；
• option-config-file.md：配置文件格式、多配置与 workspace 支持。