TanStack Router 中服务端代码泄漏到客户端的问题分析与解决

在基于 TanStack Start 框架开发应用时，开发者可能会遇到一个棘手的问题：服务端专用包（如数据库驱动 drizzle）被意外打包到客户端 bundle 中。本文将深入分析这一问题的成因，并提供完整的解决方案。

问题现象

当使用 TanStack Query 在服务端获取会话信息时，即使相关代码位于 serverFn 后面，某些服务端专用依赖（如 drizzle）仍会被错误地包含在客户端 bundle 中。这会导致两个严重后果：

1. 客户端 JavaScript 执行失败，控制台报错
2. 不必要的服务端代码被发送到浏览器，增加 bundle 体积

根本原因

经过技术分析，发现问题源于 TypeScript 配置中的 verbatimModuleSyntax: true 设置。这个标志位会严格处理类型导入，导致以下转换链：

1. 原始代码：import { something, type Thing } from "./only-server-code"
2. 服务端/客户端分离后：import { type Thing } from "./only-server-code"
3. 经过 tsc/esbuild/rollup 处理后：import { } from "./only-server-code"

这种转换最终保留了空导入语句，使得服务端代码的引用被保留在客户端 bundle 中。

解决方案

方法一：修改 tsconfig.json

最简单的解决方案是移除 verbatimModuleSyntax: true 配置。具体步骤如下：

1. 打开项目根目录下的 tsconfig.json 文件
2. 确保 compilerOptions 中不包含 "verbatimModuleSyntax": true
3. 重新启动开发服务器

这种方法能有效解决问题，但需要注意一个潜在影响：如果被移除的导入包含副作用（side effects），这些副作用将不会被执行。

方法二：显式类型声明

对于追求更严谨解决方案的开发者，可以采用显式类型声明的方式：

1. 避免从服务端模块直接导入类型
2. 将共享类型提取到独立的 .d.ts 声明文件中
3. 使用类型断言而非类型导入

这种方法虽然需要更多重构工作，但能从根本上避免类型导入导致的问题。

最佳实践建议

1. 代码组织：严格分离服务端和客户端代码到不同目录
2. 类型设计：为共享类型创建专门的类型定义文件
3. 依赖管理：定期检查客户端 bundle 内容，确保没有服务端依赖泄漏
4. 构建检查：在 CI/CD 流程中加入 bundle 分析步骤

总结

TanStack Start 框架中的服务端代码泄漏问题通常源于 TypeScript 配置不当。通过调整 verbatimModuleSyntax 设置或重构类型导入方式，开发者可以有效地解决这一问题。理解这一问题的成因也有助于预防类似情况在其他场景下发生。

对于新项目，建议从一开始就遵循清晰的架构规范，明确区分服务端和客户端代码边界，这样可以避免后期出现类似的打包问题。