tsdown 插件体系实战：Rolldown / Unplugin / Rollup / Vite 跨生态插件接入指南（基于 AIRI 仓库真实配置）

tsdown 插件体系实战Rolldown / Unplugin / Rollup / Vite 跨生态插件接入指南基于 AIRI 仓库真实配置【免费下载链接】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本文以 AIRI 仓库中的 tsdown 高级参考文档advanced-plugins.md为主体完整梳理 tsdown 基于 Rolldown 的四大插件生态Rolldown、Unplugin、Rollup、Vite的接入方式、兼容性边界与类型处理策略并对照仓库内 29 个tsdown.config.ts真实配置——尤其是proj-airi/i18n包中unplugin-yaml/rolldown的生产级用法——说明跨生态插件在实际 monorepo 中如何落地、排序与排障。tsdown 的插件体系建立在 Rolldown 之上tsdown 是一个由 Rolldown 与 Oxc 驱动的 TypeScript/JavaScript 库打包器。从 SKILL.md 可以看到两个关键前提运行时要求tsdown 本身需要Node.js 22.18.0 或更高版本才能运行仅限构建期但通过target选项构建产物可以面向更低版本的 Node.js如target: node18、target: node20即构建锁 22产物不锁 22。扩展点tsdown 的配置函数defineConfig暴露了标准的plugins字段该字段直接透传给底层的 Rolldown 打包引擎。因此凡是 Rolldown 能消费的插件对象都可以进入 tsdown 的构建管线。在 AIRI 仓库中tsdown 的版本由根目录 package.json 通过 pnpm catalogtsdown: catalog:统一管理各包按需引用。仓库内共有 29 个包级tsdown.config.ts如packages/audio/tsdown.config.ts、packages/plugin-sdk/tsdown.config.ts、services/computer-use-mcp/tsdown.config.ts等其中绝大多数配置只使用entry、format、dts等原生选项真正显式使用plugins字段的是proj-airi/i18n——它恰好是本文Unplugin 生态一节的活例子后文会完整拆解。四大插件生态与兼容性总览按 tsdown 文档的划分可接入的插件来自四个生态兼容程度依次递减1. Rolldown 插件完全兼容为 Rolldown 原生设计的插件直接放进plugins数组即可无需任何类型处理import RolldownPlugin from rolldown-plugin-something export default defineConfig({ plugins: [RolldownPlugin()], })兼容性完全支持。这是最推荐的路线——插件与打包引擎同源类型与钩子语义完全对齐。例如 SKILL.md 中 WASM 示例使用的rolldown-plugin-wasm即属此类import { wasm } from rolldown-plugin-wasm import { defineConfig } from tsdown export default defineConfig({ entry: [src/index.ts], plugins: [wasm()], })2. Unplugin绝大多数可用Unplugin 是跨打包器的万能插件框架同一插件通常会导出各宿主打包器的适配入口如.rolldown()/.vite()/.rollup()。tsdown 中直接使用其 rolldown 适配import UnpluginPlugin from unplugin-something export default defineConfig({ plugins: [UnpluginPlugin.rolldown()], })兼容性大多数unplugin-*插件可用。文档给出的典型例子包括unplugin-vue-components、unplugin-auto-import、unplugin-icons。这正是 AIRI 仓库里真实使用的模式。packages/i18n/tsdown.config.ts 通过unplugin-yaml/rolldown入口加载 YAML 插件让该国际化包能够在 TypeScript 源码中直接import仓库 packages/i18n/src 下大量 YAML 词条文件en/、zh-Hans/、ja/、ko/等目录import Yaml from unplugin-yaml/rolldown import { defineConfig } from tsdown export default defineConfig({ entry: { index: src/index.ts, locales/index: src/locales/index.ts, locales/en/index: src/locales/en/index.ts, locales/zh-Hans/index: src/locales/zh-Hans/index.ts, }, copy: [ { from: src/locales, to: dist/locales }, ], unbundle: true, plugins: [ Yaml(), ], })这个配置同时展示了插件与 tsdown 其他选项的协同entry对象语法多入口以输出名 → 源文件映射定义为每个语言子路径单独生成入口unbundle: true保持目录结构逐文件输出bundleless配合多入口形成与src/locales对应的产物布局copy将src/locales原样拷贝到dist/locales保证运行时可读取原始 YAMLplugins: [Yaml()]在解析阶段把 YAML 文件转成可 import 的 JS 模块。产物路径在 packages/i18n/package.json 的exports字段中得到印证./dist/index.mjs、./dist/locales/...等其build脚本就是裸的tsdown——即配置全部收敛在一个tsdown.config.ts中。3. Rollup 插件高兼容但可能遇到类型冲突Rollup 插件的钩子签名与 Rolldown 高度同构因此大多数 Rollup 插件可以直接工作。用法上与其他插件无异import RollupPlugin from rollup/plugin-something export default defineConfig({ plugins: [RollupPlugin()], })兼容性高。但存在一个实际工程问题Rollup 的Plugin类型与 Rolldown 的Plugin类型并不严格兼容直接传入可能触发 TypeScript 类型错误。文档给出两种消解方式import RollupPlugin from rollup-plugin-something export default defineConfig({ plugins: [ // ts-expect-error Rollup plugin type mismatch RollupPlugin(), // Or cast to any RollupPlugin() as any, ], })注意这里ts-expect-error与as any是二选一的写法ts-expect-error语义更明确若将来类型对齐了它本身会报错提醒删除as any则更省事。4. Vite 插件有限支持仅限未依赖 Vite 私有 API 的插件部分 Vite 插件在纯 Rollup 钩子层面也能跑但任何依赖 Vite 特有 API如this.environment、configResolved中的 Vite 私有字段、server/ws对象等的插件在 tsdown 中都会失效。文档给出的写法同样是靠类型断言压住编译器import VitePlugin from vite-plugin-something export default defineConfig({ plugins: [ // ts-expect-error Vite plugin type mismatch VitePlugin(), ], })兼容性有限。文档明确标注改进支持是后续版本的方向Improved support planned for future releases。因此接入 Vite 插件前应先在插件文档中确认它是否依赖 Vite 独有 API。在配置中使用插件三种基本形态基本用法plugins是defineConfig顶层字段与entry等选项并列import { defineConfig } from tsdown import SomePlugin from some-plugin export default defineConfig({ entry: [src/index.ts], plugins: [SomePlugin()], })AIRI 仓库中不使用插件的最小化配置可参考 packages/core-agent/tsdown.config.ts多入口 dts: true声明文件生成与 packages/plugin-sdk/tsdown.config.ts4 个入口 format: esmdts: true——说明plugins字段是可选的只在确有转译/注入需求时才需要添加。多个插件数组顺序即声明顺序import PluginA from plugin-a import PluginB from plugin-b import PluginC from plugin-c export default defineConfig({ entry: [src/index.ts], plugins: [ PluginA(), PluginB({ option: true }), PluginC(), ], })条件插件defineConfig接受函数形态收到包含watch等运行时信息的options可据此动态裁剪插件列表。[...].filter(Boolean)用于过滤掉条件不成立时产生的false项export default defineConfig((options) ({ entry: [src/index.ts], plugins: [ SomePlugin(), options.watch DevPlugin(), !options.watch ProdPlugin(), ].filter(Boolean), }))这与 tsdown 的条件配置能力defineConfig((options) ({...}))可用于按 watch 状态切换minify/sourcemap是同一机制的插件层面应用。常见插件模式文档列举了六类高频场景覆盖模块转译与代码注入两条主线。JSON 导入import json from rollup/plugin-json export default defineConfig({ plugins: [json()], })Node Resolveimport { nodeResolve } from rollup/plugin-node-resolve export default defineConfig({ plugins: [nodeResolve()], })CommonJSimport commonjs from rollup/plugin-commonjs export default defineConfig({ plugins: [commonjs()], })常量替换Replace用于注入环境变量与版本号等构建期常量Rolldown 侧的 tree shaking 会随之消除死分支import replace from rollup/plugin-replace export default defineConfig({ plugins: [ replace({ process.env.NODE_ENV: JSON.stringify(production), __VERSION__: JSON.stringify(1.0.0), }), ], })Auto ImportUnplugin 示例注意导入路径使用 unplugin 的/rolldown子入口import AutoImport from unplugin-auto-import/rolldown export default defineConfig({ plugins: [ AutoImport({ imports: [vue, vue-router], dts: src/auto-imports.d.ts, }), ], })组件自动注册Unplugin 示例import Components from unplugin-vue-components/rolldown export default defineConfig({ plugins: [ Components({ dts: src/components.d.ts, }), ], })框架专用插件以 Vite 插件降级接入四大 UI 框架的官方插件均出自 Vite 生态在 tsdown 中属于有限兼容路线统一模式是ts-expect-error 确认插件不依赖 Vite 运行时 API。Reactimport react from vitejs/plugin-react export default defineConfig({ entry: [src/index.tsx], plugins: [ // ts-expect-error Vite plugin react(), ], })Vueimport vue from vitejs/plugin-vue export default defineConfig({ entry: [src/index.ts], plugins: [ // ts-expect-error Vite plugin vue(), ], })Solidimport solid from vite-plugin-solid export default defineConfig({ entry: [src/index.tsx], plugins: [ // ts-expect-error Vite plugin solid(), ], })Svelteimport { svelte } from sveltejs/vite-plugin-svelte export default defineConfig({ entry: [src/index.ts], plugins: [ // ts-expect-error Vite plugin svelte(), ], })需要说明对库场景而言框架编译更多时候可以不走 Vite 插件。例如 React 的 JSX 转换在 tsdown 中可通过inputOptions: { jsx: { runtime: automatic } }这类 Rolldown 选项完成见 SKILL.md 的 React Component Library 模式框架插件更适合需要在构建期做 SFC 编译、Solid/Svelte 编译等文件级转译的场景。编写自定义插件如果现成生态插件都不满足需求可以直接写 Rolldown 插件——因为 tsdown 的plugins字段最终交给 Rolldown 执行钩子语义与 Rolldown 插件 API 完全一致transform、resolveId、load等。基本结构import type { Plugin } from rolldown function myPlugin(): Plugin { return { name: my-plugin, // Transform hook transform(code, id) { if (id.endsWith(.custom)) { return { code: transformCode(code), map: null, } } }, // Other hooks... } }要点插件以工厂函数形式导出myPlugin()便于接收选项name必填是调试时识别插件的唯一标识transform返回{ code, map }不需要 sourcemap 时显式传map: null类型从rolldown包导入而不是rollup或vite这样类型检查零断言。在 tsdown 配置中启用import { myPlugin } from ./my-plugin export default defineConfig({ plugins: [myPlugin()], })插件顺序与配置插件专属选项每个插件的选项以该插件自身文档为准——Unplugin 插件通常支持enforcepre/post、include/exclude等过滤参数Rolldown 插件则以各自 README 为准。执行顺序插件按声明顺序执行。同一条模块经过resolveId/load/transform等钩子时先声明的插件先拿到处理机会export default defineConfig({ plugins: [ PluginA(), // Runs first PluginB(), // Runs second PluginC(), // Runs last ], })排障时应把顺序问题列为必查项比如常量替换类插件若排在引入这些常量的插件之后替换就可能落空。故障排查Rollup / Vite 插件报类型错误统一用类型断言处理plugins: [ // Option 1: ts-expect-error // ts-expect-error Plugin type mismatch SomePlugin(), // Option 2: as any SomePlugin() as any, ]插件不生效文档给出的四步排查法核对兼容性——确认插件支持的目标打包器是 Rolldown 而非仅 Vite阅读插件文档——某些插件需要额外的 peer 依赖或宿主侧注册检查插件顺序——部分插件存在执行顺序依赖开启调试模式——使用--debug标志运行 tsdown 观察构建管线。Vite 插件失败Vite 插件可能依赖 Vite 特有 API按优先级尝试找 Rollup 等价物——优先找同名或同作者的 Rollup 版本插件改用 Unplugin 版本——查看是否存在unplugin-*替代如vite-plugin-icons↔unplugin-icons等待官方支持——tsdown 对 Vite 插件的支持在持续改进中。经验清单优先选 Rolldown 原生插件——兼容性最好零类型断言跨打包器需求选 Unplugin——一份插件多处复用注意使用.rolldown()入口Rollup/Vite 插件做好类型断言——ts-expect-error或as any跨生态插件务必充分测试——同一插件在不同宿主下行为可能有细微差异查阅插件自身文档获取其配置项特殊需求写自定义插件——按 Rolldown 插件 API 开发即可直接用于 tsdown。在 AIRI 仓库中如何验证这套体系全局搜索 29 个tsdown.config.ts绝大多数包如 packages/core-agent/tsdown.config.ts、packages/plugin-sdk/tsdown.config.ts、packages/server-runtime/tsdown.config.ts仅使用entrydtsformat等原生选项印证了能不用插件就不用的轻量路线唯一的显式插件使用者 packages/i18n/tsdown.config.ts 选择了 Unplugin 生态的unplugin-yaml/rolldown且与unbundle: true、多入口、copy组合是该文档Unplugin 兼容性可用结论的仓库内实证版本治理上tsdown 通过根 package.json 的 pnpm catalog 统一版本各包不各自 pin 版本保证插件生态兼容行为在整个 monorepo 内一致。相关文档生命周期钩子Hooks高级 Rolldown 配置选项React 配方含插件Vue 配方含插件【免费下载链接】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），仅供参考