作者 | Daniel Curtis

譯者 | 田橙

適用于 React 的開源類型安全搜索參數(shù)狀態(tài)管理器 Nuqs，于 2025 年 React Advanced 大會(huì) 亮相，展示了 URL 狀態(tài)管理如何為整個(gè) React 生態(tài)的應(yīng)用開發(fā)帶來變革。

在 11 月 28 日于倫敦舉行的 React Advanced 2025 大會(huì)上，自由軟件工程師 Fran?ois Best 介紹了他開發(fā)的開源庫 Nuqs。該庫目前已被 Sentry、Supabase、Vercel、Clerk 等公司采用。演講圍繞一個(gè)核心主題展開：將應(yīng)用狀態(tài)存儲(chǔ)在 URL 的查詢參數(shù)中，能夠解鎖傳統(tǒng)狀態(tài)管理方式難以實(shí)現(xiàn)的能力。

Best 將“URL 狀態(tài)”定義為把應(yīng)用數(shù)據(jù)存儲(chǔ)在 URL 的 query string 中，并將其帶來的優(yōu)勢總結(jié)為兩種“超能力”。第一種是“瞬移”（teleportation）：用戶可以分享一個(gè)鏈接，完整保留當(dāng)前的應(yīng)用狀態(tài)，接收者打開后看到的界面與分享者完全一致，可以無縫繼續(xù)操作。第二種是“時(shí)光回溯”（time travel）：借助瀏覽器書簽和歷史記錄，用戶可以輕松回到應(yīng)用曾經(jīng)的任意狀態(tài)。

在實(shí)現(xiàn)層面，Nuqs 用 useQueryState 替代了 React 中常見的 useState，實(shí)現(xiàn)組件狀態(tài)與 URL 參數(shù)之間的自動(dòng)同步。庫內(nèi)置了一系列解析器，可將 URL 字符串轉(zhuǎn)換為整數(shù)、布爾值、日期等帶類型的值，從而在整個(gè)應(yīng)用中保證類型安全。通過適配器機(jī)制，Nuqs 支持主流 React 框架，包括 Next.js（App Router 與 Pages Router）、Remix、React Router 以及 TanStack Router。

演講還展示了 Nuqs 在應(yīng)對 URL 狀態(tài)管理常見問題方面的一些高級特性?！皶r(shí)間安全”（time safety）機(jī)制將 UI 更新與 URL 更新解耦，既能保持界面響應(yīng)迅速，又能避免瀏覽器對 URL 更新頻率的限制。節(jié)流（throttling）和防抖（debouncing）功能可防止在文本輸入等高頻交互場景下觸發(fā)過多網(wǎng)絡(luò)請求。通過與 React 的useTransition集成，在服務(wù)端渲染觸發(fā)更新時(shí)還能顯示加載指示。此外，Nuqs 支持 URL 鍵名映射，開發(fā)者可以在代碼中使用語義清晰的變量名，同時(shí)為最終用戶保留簡潔、易讀的 URL。

在測試方面，Nuqs 提供了專門的測試適配器，用于模擬所需功能，開發(fā)者可對初始 URL 值的加載過程與搜索參數(shù)的更新邏輯開展全面測試。Best 提到，該項(xiàng)目在 GitHub 上已接近 1 萬顆 Star，目前主要由他在業(yè)余時(shí)間維護(hù)，同時(shí)也不斷有社區(qū)貢獻(xiàn)者加入。

Best 也強(qiáng)調(diào)了 URL 狀態(tài)管理的一些重要限制。首先是 URL 長度的現(xiàn)實(shí)約束，用戶更傾向于短且易讀的鏈接。其次，一旦 URL 被分享，就無法再控制其內(nèi)容，因此在修改查詢參數(shù)結(jié)構(gòu)時(shí)需要考慮遷移方案。出于安全原因，瀏覽器會(huì)對 URL 更新頻率進(jìn)行限制，這要求開發(fā)者謹(jǐn)慎設(shè)計(jì)狀態(tài)更新邏輯。此外，URL 參數(shù)本身構(gòu)成了應(yīng)用的入口點(diǎn)，應(yīng)用需設(shè)計(jì)健壯的狀態(tài)機(jī)以處理用戶的直接導(dǎo)航請求。

開發(fā)者社區(qū)對 Nuqs 的反響總體積極。一段名為《一款頂尖的類型安全 URL 狀態(tài)管理器》的視頻重點(diǎn)介紹了該庫在解析、節(jié)流、默認(rèn)值處理以及服務(wù)端渲染方面的能力。一位為 DevFullstack 撰稿的開發(fā)者甚至認(rèn)為，Nuqs 有潛力取代 React 現(xiàn)有的狀態(tài)管理方案，因?yàn)樗谑褂梅绞缴吓cuseState幾乎完全一致，只是把狀態(tài)存儲(chǔ)在了 URL 中。

Nuqs 是由 Fran?ois Best 主要維護(hù)的開源項(xiàng)目，采用 MIT 許可證，并在 GitHub 上保持活躍開發(fā)。該類庫經(jīng) Gzip 壓縮后體積約為 6KB，全面支持 TypeScript，并在服務(wù)端與客戶端組件之間提供端到端的類型安全保障。

https://www.infoq.com/news/2025/12/nuqs-react-advanced/

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