作者 | Daniel Curtis

譯者 | 平川

TanStack Start 引入了 導(dǎo)入保護(hù)功能，這是一種基于 Vite 的機(jī)制，旨在防止僅限服務(wù)器的代碼泄露到客戶端包中，以及僅限客戶端的代碼泄露到服務(wù)器包中。該功能于 2026 年 2 月在 X 上 發(fā)布，目前仍標(biāo)記為實(shí)驗(yàn)性功能，在所有新的 TanStack Start 項(xiàng)目中會(huì)默認(rèn)啟用。

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

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

對(duì)于不符合命名規(guī)范的文件，開發(fā)者可以在文件開頭使用一個(gè)有副作用的導(dǎo)入語句，明確地將模塊標(biāo)記為僅限服務(wù)器端或僅限客戶端：

export const API_KEY = process.env.API_KEY

該插件會(huì)記錄這個(gè)標(biāo)記，如果后續(xù)這個(gè)文件從錯(cuò)誤的環(huán)境導(dǎo)入，該限制就會(huì)強(qiáng)制執(zhí)行。它還可以為整個(gè)目錄或特定的 npm 包添加自定義拒絕規(guī)則，如在vite.config.ts中使用importProtection.client.specifiers選項(xiàng)，阻止@prisma/client或bcrypt進(jìn)入客戶端打包文件。

它在開發(fā)環(huán)境和生產(chǎn)環(huán)境中的行為有所不同。在開發(fā)過程中，違規(guī)行為默認(rèn)會(huì)觸發(fā)mock模式，將違規(guī)導(dǎo)入替換為遞歸 Proxy，并記錄一條告警信息，同時(shí)允許當(dāng)前工作繼續(xù)進(jìn)行。在構(gòu)建時(shí)，默認(rèn)行為會(huì)切換為error模式，此時(shí)構(gòu)建過程會(huì)中止，并顯示詳細(xì)的診斷信息，包括：完整的導(dǎo)入鏈、包含違規(guī)行的代碼片段以及可操作建議（如將邏輯封裝在createServerFn()、createServerOnlyFn()或createIsomorphicFn()中）。

Next.js 通過 React 服務(wù)器組件（RSC）和社區(qū)開發(fā)的server-only包來處理類似的問題。在很大程度上，這些方案依賴于 RSC 模型，而 TanStack Start 目前尚未支持該模型。在 Reddit 上有一則討論 TanStack 與 Next.js 安全性的帖子，Tanstack 生態(tài)系統(tǒng)的創(chuàng)建者 Tanner Linsley 對(duì)此進(jìn)行了回復(fù)，并就安全性問題澄清如下：

盡管 TanStack 的攻擊面比較小，但它與 Next 一樣，內(nèi)置了相同的預(yù)防性安全措施。鑒于近期 CVE 漏洞的數(shù)量激增，我們不僅及時(shí)跟進(jìn)了已知的 CVE 漏洞，而且還不斷地對(duì)框架進(jìn)行小心地審計(jì)，以防范其他未知或新出現(xiàn)的攻擊途徑。

他接著承認(rèn)，最終難免會(huì)發(fā)現(xiàn)一些問題，但他相信，這些問題的嚴(yán)重程度不會(huì)像 近期的 CVE 那樣：

毫無疑問，隨著 Start 越來越受歡迎，終究會(huì)出現(xiàn)一些我們尚未發(fā)現(xiàn)的問題，但請(qǐng)放心，它們出現(xiàn)的形式很可能不會(huì)像其他框架中現(xiàn)有 / 已知的漏洞。

這條發(fā)布在 X 上的 公告帖 獲得了超過 590 個(gè)點(diǎn)贊和 21 條評(píng)論，用戶的反響可謂積極，其中一位用戶表示終于可以放心了。

GitHub 上的一則問題報(bào)告 指出，當(dāng)服務(wù)器端代碼被意外地導(dǎo)入到客戶端時(shí)，TanStack Start 的早期版本會(huì)生成晦澀難懂且難以調(diào)試的錯(cuò)誤信息，新功能所提供的詳細(xì)違規(guī)追蹤信息正是針對(duì)這一問題而設(shè)計(jì)的。

想要升級(jí)版本的團(tuán)隊(duì)?wèi)?yīng)查閱 導(dǎo)入保護(hù)功能的文檔，并在 Vite 配置中檢查插件的加載順序（如果使用了 TypeScript 路徑別名）。該功能在新項(xiàng)目中不需要手動(dòng)啟用，只有在 TanStack Start Vite 插件的配置中顯式設(shè)置importProtection: { enabled: false }時(shí)，它才會(huì)被禁用。

TanStack Start 是一個(gè)基于 TanStack Router 構(gòu)建并由 Vite 驅(qū)動(dòng)的全棧 React 框架，支持服務(wù)器端渲染（SSR）、流式處理、服務(wù)器函數(shù)、打包，并可在任何托管服務(wù)商或運(yùn)行時(shí)環(huán)境中部署。目前，該項(xiàng)目處于候選發(fā)布（Release Candidate）階段。

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

聲明：本文為 InfoQ 翻譯，未經(jīng)許可禁止轉(zhuǎn)載。