本技能介绍 TanStack Devtools 在生产与开发环境中的处理方式,前置要求是先阅读 devtools-app-setup 技能,因为初始设置(框架适配器、Vite 插件、依赖类型)决定采用哪种生产策略。
用途:控制 devtools 是否进入生产构建,兼顾开发便利与生产包体积。
主要能力与机制:
- Vite 插件自动剥离。@tanstack/devtools-vite 含子插件 @tanstack/devtools:remove-devtools-on-build,removeDevtoolsOnBuild 默认 true,在 vite build 及 mode 为 production 的非 serve 命令中运行。它用 oxc-parser 解析源文件,移除来自 @tanstack/react-devtools、@tanstack/preact-devtools、@tanstack/solid-devtools、@tanstack/vue-devtools、@tanstack/svelte-devtools、@tanstack/angular-devtools、@tanstack/devtools 的导入及其 JSX 元素,并追踪 plugins 数组内的插件引用,移除不再使用的导入。标准 Vite 项目默认即可正确处理生产构建,无需额外配置。
- 条件导出。@tanstack/devtools 核心包用 package.json 条件导出区分 bundle:browser + development 解析到 dev.js,browser 单独解析到 index.js,node 与 workerd 解析到 server.js。
两种工作流: 开发专用(默认推荐):以 devDependencies 安装,npm install -D @tanstack/react-devtools @tanstack/devtools-vite;Vite 配置使用 devtools() 默认剥离;应用代码直接导入 TanStackDevtools,构建时导入与 JSX 被移除。 有意生产使用:需三处改动——改为常规依赖 npm install @tanstack/react-devtools @tanstack/devtools-vite;Vite 配置 devtools({ removeDevtoolsOnBuild: false });应用代码不变。可结合 requireUrlFlag 与 urlFlag(如 'debug')隐藏 UI。
非 Vite 项目:无自动剥离,需手动处理。策略 A:条件动态导入,将 devtools 单独成文件,用 process.env.NODE_ENV === 'development' 判断导入;策略 B:利用 bundler 的 define/replace 做静态可判定的死代码消除,条件须可静态求值。
NoOp 插件变体:使用 @tanstack/devtools-utils 的工厂函数返回 [Plugin, NoOpPlugin] 元组,NoOpPlugin 渲染空片段、无真实依赖,便于库作者做 tree-shaking。React、Preact、Solid、Vue 等适配器均如此,消费者可按环境选择变体。
@tanstack/devtools-webmcp:根导入在 NODE_ENV 为 development 时是真实 helper,其他环境为 no-op;若生产也要注册工具,导入 @tanstack/devtools-webmcp/production。
常见错误:想在生生产保留 devtools 却未同时禁用剥离并改为常规依赖;非 Vite 项目未手动排除;插件库未导出 NoOp 变体。
限制与设计取舍:开发便利与生产显式包含两条路径在依赖和配置上互斥,项目须选定其一。混用(如保留 devDependency 却设 removeDevtoolsOnBuild: false)在生产裁剪 devDependencies 时会静默失败。预发/预览环境建议保持开发工作流并用 requireUrlFlag,而非切换到生产工作流。其余未在资料中说明的细节暂未提供。