GitHub 上有個(gè) 400+ star 的開源項(xiàng)目，核心功能一句話就能說(shuō)清：讓 URL 參數(shù)支持真正的 JavaScript 對(duì)象——包括 Date、嵌套數(shù)組、復(fù)雜結(jié)構(gòu)，還能保持完整的 TypeScript 類型推導(dǎo)。開發(fā)者自己也沒想到，這個(gè)從 dashboard frustrations 里長(zhǎng)出來(lái)的工具，會(huì)被這么多人用。

state-in-url 的作者最近寫了完整復(fù)盤。不是技術(shù)布道，是實(shí)打?qū)嵉牟瓤佑涗洠簽槭裁船F(xiàn)有方案總差一口氣、編碼器怎么調(diào)出來(lái)的、測(cè)試階段差點(diǎn)翻車的細(xì)節(jié)。

他遇到的問題很典型。做 dashboard 和復(fù)雜表單時(shí)，狀態(tài)永遠(yuǎn)散落在三個(gè)地方：本地變量、全局 store、還有 URL（為了分享和書簽）。同步它們像是永無(wú)止境的額外工作。其他庫(kù)要么配置繁瑣，要么把所有東西轉(zhuǎn)成字符串、丟掉類型信息。

于是他決定造一個(gè)自己每天都想用的版本。

設(shè)計(jì)目標(biāo)：像 useState 一樣簡(jiǎn)單，但狀態(tài)住在 URL 里

核心要求列得很死。返回 state 和 setter，API 完全對(duì)標(biāo) useState，但要有 TypeScript 精確感知數(shù)據(jù)結(jié)構(gòu)。真實(shí)數(shù)據(jù)類型必須能完整往返 URL，不能變成字符串就丟了形狀。支持 Next.js App Router 的 SSR、React Router、Remix，不干擾其他 query 參數(shù)。最后體積要極致——零運(yùn)行時(shí)依賴，gzip 后不到 2KB。

最讓他滿意的決策出乎意料地簡(jiǎn)單：用一個(gè)普通 JavaScript 對(duì)象同時(shí)承擔(dān)默認(rèn)值和類型定義的雙重角色。不需要單獨(dú)的 schema，不用寫復(fù)雜的泛型。

代碼長(zhǎng)這樣：

age: undefined as number | undefined,

tags: [] as { id: string; value: { text: string; time: Date } }[],

type FormState = typeof formState;

把這個(gè)對(duì)象傳給 hook，類型和默認(rèn)值就自動(dòng)對(duì)齊。這種"一物兩用"的偷懶設(shè)計(jì)，反而成了最順手的部分。

共享狀態(tài)的需求用 useSharedState 解決。底層是一個(gè)單例 JavaScript 對(duì)象，組件訂閱變化，不依賴 React Context。這讓應(yīng)用里不相干的模塊能共享同一份數(shù)據(jù)，而不必引入額外的復(fù)雜度。

編碼器的調(diào)優(yōu)：可讀性和類型保真之間的拉扯

編碼解碼器是打磨最多的部分。目標(biāo)很明確：URL 要人類可讀，同時(shí)保留真實(shí)類型。最終方案下，編碼一個(gè)較大對(duì)象在他的機(jī)器上耗時(shí)約 1 毫秒。

項(xiàng)目用 pnpm monorepo 組織，TypeScript 貫穿始終。核心邏輯獨(dú)立成一個(gè)包，Next.js、React Router、Remix 的適配器各自輕薄封裝。這種結(jié)構(gòu)讓框架特定代碼不會(huì)污染核心，也方便后續(xù)擴(kuò)展。

測(cè)試階段的故事他沒細(xì)說(shuō)，但留了線索——"testing struggles" 被專門提到。結(jié)合編碼器的復(fù)雜度，可以推測(cè)邊界情況的處理花了大量時(shí)間：Date 對(duì)象的序列化格式、嵌套數(shù)組的深度限制、特殊字符的轉(zhuǎn)義策略，這些都要在保持 URL 簡(jiǎn)潔的同時(shí)確保無(wú)損還原。

發(fā)布后的意外：被用起來(lái)的感覺

6.1.2 版本幾周前剛發(fā)布。400+ star 的數(shù)字讓他意外——"It still surprises me that people use it"。這種反應(yīng)很真實(shí)，很多開源作者都有類似體驗(yàn)：解決了自己的痛點(diǎn)，不確定是不是別人的痛點(diǎn)，結(jié)果代碼被陌生人跑在了生產(chǎn)環(huán)境里。

他放了一個(gè) live demo 在 https://state-in-url.dev。表單輸入時(shí) URL 實(shí)時(shí)變化，刷新頁(yè)面數(shù)據(jù)原封不動(dòng)，鏈接分享出去對(duì)方看到完全一致的狀態(tài)。這個(gè)演示本身就在倉(cāng)庫(kù)里，可以直接跑。

回頭看，這個(gè)項(xiàng)目的發(fā)起點(diǎn)是對(duì)"狀態(tài)碎片化"的厭倦。不是架構(gòu)層面的宏大敘事，是每天寫代碼時(shí)的具體摩擦。URL 作為 Web 最古老的基礎(chǔ)設(shè)施之一，被重新激活成了跨會(huì)話、跨用戶的狀態(tài)載體——而且用起來(lái)和本地 state 沒區(qū)別。

作者沒說(shuō)的是：當(dāng)瀏覽器地址欄能存復(fù)雜對(duì)象時(shí)，那些"先存 localStorage、再考慮同步"的折中方案，是不是該重新評(píng)估了？