人工智能AI AgentMCP 服务工具调用GUI 自动化语音数字人交互助手【免费下载链接】airi 自托管、归你拥有的 Grok 风格 AI 伴侣与 waifu / 赛博生命灵魂容器目标是接近 Neuro-sama 的高度支持实时语音聊天、Minecraft 和 Factorio 游玩支持 Web / macOS / Windows。项目地址https://gitcode.com/moeru-ai/airi点击查看免费下载tsdown 是 airi 仓库中用于打包 TypeScript/JavaScript 库的核心构建工具其监听模式Watch Mode能够在源码变更时自动重建产物显著缩短库开发的迭代反馈回路。本文以 tsdown 的 Watch Mode 官方参考文档为主体结合 airi 仓库中真实存在的tsdown.config.ts配置文件如 packages/core-agent/tsdown.config.ts、packages/i18n/tsdown.config.ts系统讲解监听模式的 CLI 用法、配置项、高级模式与故障排查读完即可在自己的库开发流程中落地一套高效、可复制的热重建工作流。一、Watch Mode 是什么Watch Mode 会持续监控你的源文件并在文件发生变化时自动触发重新构建从而把改代码 → 手动跑构建 → 查看产物的多步流程压缩为改代码 → 自动出产物一步。它面向的是开发阶段而非生产发布监听期间每次构建都是增量式的只重编发生变化的模块链比全量构建更快你可以把测试、启动 dev server 等后续动作挂在构建成功之后onSuccess让产物一变测试或本地服务立刻跟上它不要求你手动反复执行tsdown是 tsup 用户迁移到 tsdown 后首选的开发替代方案。tsdown 基于 Rolldown 与 Oxc 构建运行时要求 Node.js 22.18.0 或更高仅构建期但产物可以通过target选项降级到更低的 Node.js 版本不影响库的运行时兼容性。相关基础说明可参考 tsdown SKILL 文档 与 Getting Started 指南。二、基础用法CLI 与配置文件2.1 CLI 启动# 监听所有项目文件 tsdown --watch # 或使用短标志 tsdown -w # 监听指定目录 tsdown --watch ./src # 监听指定文件 tsdown --watch ./src/index.ts--watch与-w完全等价--watch后面还可以跟一个可选的路径参数用于把监听范围收敛到某个目录或单个入口文件参见 CLI Reference 中--watch, -w [path]一节。2.2 配置文件启用export default defineConfig({ entry: [src/index.ts], watch: true, })设置watch: true后只要以tsdown启动无需额外加--watch便会进入监听模式。CLI 标志与配置文件的关系遵循CLI 覆盖配置文件的优先级规则--no-watch可以临时关闭配置文件中的监听开关。三、Watch 选项详解3.1 忽略路径Ignore Paths某些文件如测试、fixtures、临时文件的变动不应触发重建可通过--ignore-watch排除tsdown --watch --ignore-watch test --ignore-watch **/*.test.ts配置文件中的等价写法使用watch.excludeexport default defineConfig({ entry: [src/index.ts], watch: { exclude: [test/**, **/*.test.ts], }, })3.2 构建成功后执行命令On Success Command监听模式下最常见的需求是构建完立刻做点什么——跑测试、启动服务、发通知# 构建成功后打印提示 tsdown --watch --on-success echo Build complete! # 构建成功后直接运行产物 tsdown --watch --on-success node dist/index.mjsexport default defineConfig({ entry: [src/index.ts], watch: true, onSuccess: node dist/index.mjs, })onSuccess接收的是 shell 命令字符串仅在构建成功时执行构建失败时不会触发方便你在出错时直接查看终端中的报错而非被后续命令掩盖。更多用法见 On Success。四、Watch 行为机制4.1 默认监听目标默认情况下 tsdown 监听三类内容所有入口文件entry中声明的文件所有被入口导入的文件import 链上的模块配置文件本身如tsdown.config.ts变更时触发重启。这意味着监听范围是跟随模块依赖图动态变化的新增一个被入口导入的文件它会自动进入监听范围反之从依赖图中移除的文件也会自动退出监听无需手动维护路径列表。4.2 文件变更处理策略不同文件的变更触发不同级别的处理变更对象处理方式源文件增量重建incremental rebuild配置文件完全重启并清空缓存full restart with cache clear依赖dependencies若被入口导入则重建对应模块配置文件的变更之所以要完全重启是因为解析配置后缓存了入口、格式、插件等关键决策热替换容易引入不一致状态直接重启反而最可靠。4.3 键盘快捷键监听进程存活期间可直接用键盘控制r—— 手动触发一次重建手动重建q—— 退出监听模式。这两个快捷键让手动控制构建节奏无需另开终端配合onSuccess使用尤其顺手。五、常见模式把 Watch 用出生产力5.1 开发模式一键切换利用defineConfig支持函数参数的特性可以基于options.watch一键在开发与生产两套配置间切换export default defineConfig((options) ({ entry: [src/index.ts], format: [esm], watch: options.watch, sourcemap: options.watch, // 开发时生成 source map 便于调试 minify: !options.watch, // 生产时才压缩 }))关于sourcemap的三种形态外置 / inline / hidden及与watch的搭配见 Sourcemap 文档。5.2 构建后自动跑测试把测试作为onSuccess实现保存即测export default defineConfig({ entry: [src/index.ts], watch: true, onSuccess: npm run test, })5.3 多入口监听对象形式的entry同样受支持多个入口各自产出独立 bundleexport default defineConfig({ entry: { main: src/index.ts, cli: src/cli.ts, }, watch: true, clean: false, // 每次重建不清空输出目录 })clean: false在监听模式下的意义在于反复重建时避免反复清空/重写整个输出目录加快增量构建。完整的行为权衡见 Cleaning 文档。5.4 与测试运行器 / dev server 集成# 变更后自动跑 vitest tsdown --watch --on-success vitest run # 变更后自动重启本地服务 tsdown --watch --on-success node dist/server.mjsairi 仓库中大量包都同时配备了 tsdown 与 vitest如 packages/core-agent、packages/provider-inference这一组合正是上述模式的典型应用场景。5.5 Monorepo 包监听结合workspace支持一份配置即可监听多个子包export default defineConfig({ workspace: packages/*, entry: [src/index.ts], watch: { exclude: [**/test/**, **/*.spec.ts], }, })原文档此处同时声明了顶层watch: true与watch: { exclude }两个同名键二者语义等价于开启监听并排除测试路径。在真实的 TypeScript 配置中请像上面这样把exclude收敛进watch对象里避免同名键覆盖。airi 仓库即采用 pnpm workspace tsdown 的 monorepo 布局见根目录 package.json 与 pnpm-workspace.yaml仓库内共有 35 个tsdown.config.ts例如packages/plugin-sdk/tsdown.config.ts多入口 dts: trueformat: esmservices/computer-use-mcp/tsdown.config.ts多入口 target: node18clean: truedts: truepackages/audio/tsdown.config.ts对象入口 unbundle: trueexternalpackages/i18n/tsdown.config.ts对象入口 copyunbundle: true unplugin 插件。给这些包的开发流程加上--watch即可在改动任一子包源码后即时获得增量产物。六、高级配置6.1 自定义 Watch 选项watch除了true/false还支持对象形式以精细化控制export default defineConfig({ entry: [src/index.ts], watch: { include: [src/**], // 额外纳入监听的路径 exclude: [**/*.test.ts, **/fixtures/**], // 忽略的 glob 路径 skipWrite: false, // 是否跳过写入产物 }, })include在默认监听目标入口 导入链 配置文件之上追加需要关注的目录exclude从监听范围中剔除的 glob 模式防止测试、fixtures 等无关变更触发重建skipWrite控制重建后是否实际写出产物文件对只想验证构建不落盘的场景有用。6.2 条件式 WatchConditional Watch在函数式配置中按 watch 状态裁剪能力让同一份配置同时服务开发与发布export default defineConfig((options) { const isDev options.watch return { entry: [src/index.ts], format: [esm], dts: !isDev, // 监听模式下跳过 DTS 生成加快重建 sourcemap: isDev, clean: !isDev, } })这里的关键取舍dts类型声明生成与minify压缩都是重建耗时大户开发期关闭、发布期开启是让 watch 保持秒级反馈的核心技巧。DTS 相关的isolatedDeclarations加速手段见 DTS 文档。七、CLI 速查表# 基础监听 tsdown -w # 监听 source map tsdown -w --sourcemap # 监听但不清理输出目录 tsdown -w --no-clean # 监听 构建成功后执行命令 tsdown -w --on-success npm test # 只监听指定格式 tsdown -w --format esm # 监听 压缩 tsdown -w --minify # 监听 忽略测试文件 tsdown -w --ignore-watch **/*.test.ts八、使用建议活跃开发时始终开启 watch mode让产物时刻保持与源码同步监听模式下跳过 DTS 生成dts: !options.watch重建速度显著提升关闭clean避免每次重建做多余的文件系统操作善用onSuccess挂载测试、lint、重启 dev server 等后置任务忽略测试文件exclude: [**/*.test.ts]防止无关变更触发无效重建记住r/q快捷键需要时手动重建或随时退出监听。九、故障排查9.1 变更未被监听依次检查文件是否位于entry或入口的 import 依赖链上默认只监听这两类 配置文件路径是否命中了exclude或--ignore-watch的忽略模式文件系统是否支持监听网络盘、部分容器/挂载卷可能不触发事件。9.2 重建过于频繁把明显无关的路径全部排除掉export default defineConfig({ watch: { exclude: [ **/node_modules/**, **/.git/**, **/dist/**, **/*.test.ts, ], }, })9.3 重建速度慢监听模式下跳过 DTSdts: !options.watch关闭压缩minify: false开发期间收窄入口集合减少每次全量处理的模块数。9.4 配置变更未生效配置文件一旦变更tsdown 会自动触发完全重启并清空缓存因此不需要手动干预。若感觉改动没生效请确认改动的是被自动发现的配置文件本身配置文件查找规则而不是某个未被监听的引用文件。9.5 为什么不用 Stub Modetsdown不支持 stub mode。对于快速开发官方推荐以 watch mode 作为替代方案——它在没有 stub mode 诸多弊端如类型解析不一致、产物与源码脱节的前提下提供即时重建的体验。十、相关选项On Success —— 构建成功后执行命令Sourcemap —— 调试信息生成Clean —— 输出目录清理策略。完整 CLI 参考见 reference-cli.md技能总览见 tsdown SKILL.md。结合 airi 仓库中 35 个真实存在的tsdown.config.ts如 packages/plugin-sdk/tsdown.config.ts、services/computer-use-mcp/tsdown.config.ts你可以直接把本文的 watch 模式配置接入任意一个子包的开发脚本享受保存即重建、重建即验证的开发体验。赞分享人工智能AI AgentMCP 服务工具调用GUI 自动化语音数字人交互助手【免费下载链接】airi 自托管、归你拥有的 Grok 风格 AI 伴侣与 waifu / 赛博生命灵魂容器目标是接近 Neuro-sama 的高度支持实时语音聊天、Minecraft 和 Factorio 游玩支持 Web / macOS / Windows。项目地址https://gitcode.com/moeru-ai/airi点击查看免费下载相关推荐Airi 多包仓库实战tsdown Source Maps 配置全解析Airi 多包仓库实战tsdown Source Maps 配置全解析 导读 Source Maps源码映射能把打包压缩后的产物映射回原始 TypeSc人工智能AI 应用大模型AI Agent交互助手语音数字人后端前端桌面应用移动开发GUI 自动化MCP 服务AIRI 仓库实战tsdown 自动生成 package.json exports 字段完全指南AIRI 仓库实战tsdown 自动生成 package.json exports 字段完全指南 导读 exports 字段是现代 Node.js 包导出映射人工智能AI AgentMCP 服务工具调用GUI 自动化语音数字人交互助手后端tsdown minify 配置完全指南Airi 仓库的代码压缩与 DCE-Only 实践tsdown minify 配置完全指南Airi 仓库的代码压缩与 DCE Only 实践 本篇技术指南以 tsdown 的 minify 选项为主线完整讲人工智能AI AgentMCP 服务工具调用GUI 自动化语音数字人交互助手后端上一篇aliyunpan 排障速查指南登录失败、下载上传与同步备份问题定位下一篇node-postgres增删改查完全手册参数化查询与结果集处理彻底告别SQL注入创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考