TanStack Start 推出导入保护机制，强化服务器与客户端边界划分
作者 | Daniel Curtis
译者 | 平川
TanStack Start 引入了 导入保护功能，这是一种基于 Vite 的机制，旨在防止仅限服务器的代码泄露到客户端包中，以及仅限客户端的代码泄露到服务器包中。该功能于 2026 年 2 月在 X 上 发布，目前仍标记为实验性功能，在所有新的 TanStack Start 项目中会默认启用。
随着全栈 React 应用程序的复杂性不断提升，服务器端与客户端代码之间的边界已经成为导致隐蔽错误和安全风险的常见根源。如果不对导入进行严格的管理，本应仅在服务器端运行的代码（如数据库查询或访问环境的密钥）就可能会意外地进入客户端打包文件。TanStack Start 的导入保护功能旨在通过工具层面的机制来解决这一问题，而非仅依赖开发者的自律。
该系统以 Vite 插件的形式运行，会在开发和构建过程中检查源文件中的每个导入语句。导入语句可能因两种情况被拒绝：基于解析后文件路径的文件模式匹配，以及基于原始导入字符串的限定符模式匹配。在默认情况下，遵循*.server.*命名规范的文件在客户端环境中会被拒绝，而 *.client.*文件在服务器端会被拒绝。这一功能不需要任何额外的配置。限定符 @tanstack/react-start/server在客户端也会被默认屏蔽。
对于不符合命名规范的文件，开发者可以在文件开头使用一个有副作用的导入语句，明确地将模块标记为仅限服务器端或仅限客户端：
exportconstAPI_KEY= process. env. API_KEY
该插件会记录这个标记，如果后续这个文件从错误的环境导入，该限制就会强制执行。它还可以为整个目录或特定的 npm 包添加自定义拒绝规则，如在 vite.config.ts中使用 importProtection.client.specifiers选项，阻止 @prisma/client或 bcrypt进入客户端打包文件。
它在开发环境和生产环境中的行为有所不同。在开发过程中，违规行为默认会触发 mock模式，将违规导入替换为递归 Proxy，并记录一条告警信息，同时允许当前工作继续进行。在构建时，默认行为会切换为 error模式，此时构建过程会中止，并显示详细的诊断信息，包括：完整的导入链、包含违规行的代码片段以及可操作建议（如将逻辑封装在 createServerFn、createServerOnlyFn或 createIsomorphicFn中）。
Next.js 通过 React 服务器组件（RSC）和社区开发的 server-only包来处理类似的问题。在很大程度上，这些方案依赖于 RSC 模型，而 TanStack Start 目前尚未支持该模型。在 Reddit 上有一则讨论 TanStack 与 Next.js 安全性的帖子，Tanstack 生态系统的创建者 Tanner Linsley 对此进行了回复，并就安全性问题澄清如下：
尽管 TanStack 的攻击面比较小，但它与 Next 一样，内置了相同的预防性安全措施。鉴于近期 CVE 漏洞的数量激增，我们不仅及时跟进了已知的 CVE 漏洞，而且还不断地对框架进行小心地审计，以防范其他未知或新出现的攻击途径。
他接着承认，最终难免会发现一些问题，但他相信，这些问题的严重程度不会像 近期的 CVE 那样：
毫无疑问，随着 Start 越来越受欢迎，终究会出现一些我们尚未发现的问题，但请放心，它们出现的形式很可能不会像其他框架中现有 / 已知的漏洞。
这条发布在 X 上的 公告帖 获得了超过 590 个点赞和 21 条评论，用户的反响可谓积极，其中一位用户表示终于可以放心了。
GitHub 上的一则问题报告 指出，当服务器端代码被意外地导入到客户端时，TanStack Start 的早期版本会生成晦涩难懂且难以调试的错误信息，新功能所提供的详细违规追踪信息正是针对这一问题而设计的。
想要升级版本的团队应查阅 导入保护功能的文档，并在 Vite 配置中检查插件的加载顺序（如果使用了 Type 路径别名）。该功能在新项目中不需要手动启用，只有在 TanStack Start Vite 插件的配置中显式设置importProtection: { enabled: false }时，它才会被禁用。
TanStack Start 是一个基于 TanStack Router 构建并由 Vite 驱动的全栈 React 框架，支持服务器端渲染（SSR）、流式处理、服务器函数、打包，并可在任何托管服务商或运行时环境中部署。目前，该项目处于候选发布（Release Candidate）阶段。