TanStack Start 推出導入保護機制，強化服務器與客戶端邊界劃分

作者 | Daniel Curtis

譯者 | 平川

TanStack Start 引入了 導入保護功能，這是一種基于 Vite 的機制，旨在防止僅限服務器的代碼泄露到客戶端包中，以及僅限客戶端的代碼泄露到服務器包中。該功能于 2026 年 2 月在 X 上 發布，目前仍標記為實驗性功能，在所有新的 TanStack Start 項目中會默認啟用。

隨著全棧 React 應用程序的復雜性不斷提升，服務器端與客戶端代碼之間的邊界已經成為導致隱蔽錯誤和安全風險的常見根源。如果不對導入進行嚴格的管理，本應僅在服務器端運行的代碼（如數據庫查詢或訪問環境的密鑰）就可能會意外地進入客戶端打包文件。TanStack Start 的導入保護功能旨在通過工具層面的機制來解決這一問題，而非僅依賴開發者的自律。

該系統以 Vite 插件的形式運行，會在開發和構建過程中檢查源文件中的每個導入語句。導入語句可能因兩種情況被拒絕：基于解析后文件路徑的文件模式匹配，以及基于原始導入字符串的限定符模式匹配。在默認情況下，遵循*.server.*命名規范的文件在客戶端環境中會被拒絕，而*.client.*文件在服務器端會被拒絕。這一功能不需要任何額外的配置。限定符@tanstack/react-start/server在客戶端也會被默認屏蔽。

對于不符合命名規范的文件，開發者可以在文件開頭使用一個有副作用的導入語句，明確地將模塊標記為僅限服務器端或僅限客戶端：

export const API_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 配置中檢查插件的加載順序（如果使用了 TypeScript 路徑別名）。該功能在新項目中不需要手動啟用，只有在 TanStack Start Vite 插件的配置中顯式設置importProtection: { enabled: false }時，它才會被禁用。

TanStack Start 是一個基于 TanStack Router 構建并由 Vite 驅動的全棧 React 框架，支持服務器端渲染（SSR）、流式處理、服務器函數、打包，并可在任何托管服務商或運行時環境中部署。目前，該項目處于候選發布（Release Candidate）階段。

https://www.infoq.com/news/2026/03/tanstack-import-protection/

聲明：本文為 InfoQ 翻譯，未經許可禁止轉載。