TechMoon 科技月球
WordPress、SEO 與 AI 工具實測指南
TechMoon 科技月球
WordPress、SEO 與 AI 工具實測指南

shadcn/ui 官方元件登錄目錄已收錄 593 個開源 registry,光 2026 年 11 月就新增 70 個,內容從 React 元件、區塊到 AI 提示詞規則檔都有;配合 CLI 內建的 MCP 伺服器,Claude Code、Cursor、Codex 都能用自然語言搜尋並安裝元件,企業的設計系統因此多了一條機器可讀的配送路。
用 AI 摘要這篇文章:
讓 Claude Code 或 Cursor 生出一個後台介面,跑幾次之後你會發現代理手上的按鈕永遠是那一套圓角與灰階。卡點不在模型審美,在提示詞只能描述長相,保證不了代理拿到你們家設計系統裡正確版本的那顆按鈕。shadcn/ui 在 2026 年 11 月把這件事推到一條機器可讀的配送路上:官方元件登錄目錄在 10 月 31 日還收錄 525 個 registry,到 11 月 22 日已經是 593 個,三個星期新增 70 個、請走 2 個;同一條路上的 CLI 內建 MCP 伺服器,也在 10 月 27 日的 [email protected] 升級到新版協定。判斷可以先給:這條路已經能走,有設計系統的團隊值得認真對待;但該接的不是那 593 個別人的元件庫,而是把自家元件發布成 registry 的那套發布紀律。
先看數字怎麼長出來的。目錄本體是 shadcn-ui/ui 儲存庫裡的 apps/v4/registry/directory.json,10 月 31 日收完當月最後一批後是 525 筆;比對 11 月 22 日抓下的主分支版本,已經 593 筆。差集算出來:新增 70 個 namespace、移除 2 個(@agent-ui-kit 與 @catalogs),淨增加 68。十一月的收錄與移除全走 PR:
| 併入主分支日期 | PR | 對目錄做的事 |
|---|---|---|
| 11 月 2 日 | #12556 | 收錄一批社群 registry |
| 11 月 4 日 | #12589 | 收錄一批社群 registry |
| 11 月 6 日 | #12597 | 收錄一批社群 registry |
| 11 月 11 日 | #12629 | 收錄一批社群 registry |
| 11 月 17 日 | #12677、#12740 | 同日兩批收錄 |
| 11 月 17 日 | #12708 | 把 Catalogs 移出目錄 |
| 11 月 19 日 | #12763 | 收錄 @nightmarquee、@venusui 等 |
幾乎每兩三天收一批的節奏,而且往前翻這個檔案的 commit 史,加速是九月就開始的:9 月 17 日單日兩筆各收九個、9 月 29 日收十個、9 月 30 日收六個、10 月 2 日再收十個、10 月 5 日收七個。目錄裝的東西也早就超出一般意義的 UI 套件:十一月進場的有參考 Notion Calendar 做的 @calendarcn(日、星期、月與議程四種檢視,支援拖曳與調整大小)、做 CSV 匯入的 @csvjetty(欄位映射、驗證、行內修正)、走 macOS 風格的 @cupertinoui,再往前翻還有只做字排版的 @0nlytype、走黏土擬態風格的 @1st-pouf(用 Tailwind CSS v4 與 Radix UI 搭)。主題切得這麼細,看得出這個目錄收的是一種可安裝的設計語言,走的路與 npm 鏡像不同。
目錄的維護是雙向的,這點比數字本身重要。@catalogs 在 11 月 17 日被整筆移除,代表收錄之後失效或走樣的條目會被清掉。官方文件的定位也寫得直白:這份開源索引是「現成可用的開源 registry 清單」,而且 CLI 在執行 shadcn add 或 shadcn search 時會自動查它。換句話說,目錄不是官網的展示櫥窗,是命令列的實際資料來源,上架等於直接進到所有使用者的搜尋範圍。
上架的門檻與流程,官方文件給了完整交代:把 registry 加進 directory.json、跑 pnpm validate:registries 做格式驗證、開 PR 給團隊審核,合併之後立即發布。有兩個但書值得記住。Registry Health 的健康監控在發布之後才開始,不擋上架,等於品質把關分成事前審核與事後監控兩端,中間沒有保證。收錄條件則要求開源且公開可存取、符合 registry schema 的合法 JSON、平面結構(items 不得巢狀)、files 陣列不得內嵌 content 屬性;格式不對,驗證指令就會擋下來。

還有一條容易漏的路:不上目錄也照用。官方文件明講,放在 GitHub 上的 registry 用 owner/repo/item 地址就能取用,目錄只決定 @namespace 這種短名形式。內部元件庫走這條路,完全不必進公開目錄。
打開目錄裡任何一筆,起碼都有這五個欄位(部分條目另帶作者欄):name(@ 前綴的 namespace)、homepage、url、description、logo。url 是 {name}.json 模板,例如 @nightmarquee 對到 nightmarquee.com/r/{name}.json,CLI 把資源名代進去就能抓到單一元件的描述檔。所以目錄收錄的單位是「一個 registry 站」,一站裡面可以有很多元件,593 這個數字是站數,全生態的元件數量只會更多。
描述檔本身的規格是 registry.json schema:頂層有 $schema、name、homepage、include、items,根目錄必須至少給 items 或 include 其中之一。每個 item 帶 name、type(例如 registry:block、registry:component、registry:ui)、registryDependencies、dependencies、files。關鍵在前兩個依賴欄位:registryDependencies 可以引用裸名稱(button)、跨 namespace(@acme/input-form)或完整 URL;dependencies 走 npm 語意([email protected]、motion)。這代表依賴解析有明確契約,元件抓進來時該帶的 npm 套件與該先裝的其他元件,都寫在宣告裡,代理照著宣告裝就行。
檔案路徑的規則對多專案團隊有直接影響:item 的 files 路徑以宣告它的那份 registry.json 為基準讀取,而 include 可以把多份 registry.json 組合成一份更大的登錄,條件是路徑必須是相對路徑並指到明確檔案,item 名稱在組合完成的整棵樹裡必須唯一。放到 monorepo 的情境,各子專案可以各自維護元件清單,根目錄再組合成對外的單一入口,維護與治理不必綁在同一個檔案上。
資源形態也比「元件庫」三個字寬得多。namespace 文件列出的形態包含 components、libraries、utilities、hooks、AI prompts、configuration files、themes,文件自己舉的例子裡就有 @ai/chatbot-rules 這種代理規則檔。對團隊來說,這等於設計 token、主題、給代理守的規則,全都能跟元件走同一條配送與版本化路線。想在 AI 編輯器裡用規則檔約束代理的作法,可以對照 CursorList 收錄各家規則檔的整理,兩者是同一個問題的兩種解法。
自架的實際接線就兩個動作。先在專案的 components.json 加 registries 欄位,把自訂 namespace 對到 URL 模板:"registries": { "@acme": "https://registry.acme.com/resources/{name}.json" },之後就能裝了:pnpm dlx shadcn@latest add @acme/button,一次可裝多個(@acme/header @lib/auth-utils),想先看內容再用 npx shadcn@latest view @acme/button 預覽。私有登錄用物件形態設定,headers 支援 Authorization: Bearer ${REGISTRY_TOKEN} 這種寫法,環境變數會自動展開,token 放 .env.local 不進版本庫。
這套短名機制讓「公司元件」與「公開元件」在指令層同一待遇,代理裝 @acme/button 與裝 shadcn 官方 button 走完全一樣的路。想更省事的團隊,官方也支援把 GitHub 儲存庫直接當 registry 用,連主機都不用架。整合的粒度可以逐步拉:先把最常用的十來個元件上架,再收規則檔與主題,不用第一天就把整個設計系統搬上去。與 Claude Code 技能類的規則化做法相比(例如把 UI 風格守則寫成 skill 的 unslop 整理),registry 多了版本與依賴解析這一層,規則檔則贏在零部署;兩者並用不衝突。
代理這端的入口是 shadcn mcp。官方文件把它定位為「AI 助手、元件登錄與 shadcn CLI 之間的橋」,能力四項:瀏覽元件與區塊範本、跨登錄搜尋、自然語言安裝、支援多登錄。標準 shadcn/ui 登錄免設定,其他登錄照 components.json 的設定走。
這個功能不是新玩具,版本史攤開有一年以上的迭代:3.4.0(2025 年 10 月)加 Codex 支援、3.6.3(2026 年 1 月)加 opencode;4.0.0(2026 年 3 月)把舊的 registry:build 與 registry:mcp 指令淘汰;4.21.5(10 月 14 日)修掉 MCP 搜尋清單把 Promise 物件直接印成字串、看不到安裝指令的 bug;最新的 4.23.0(10 月 27 日)把伺服器升到 MCP TypeScript SDK v2,提供 2026-07-28 版協定與更早版本,匯出介面改為 McpServer,並新增每連線一個實例的 createServer()。兩代之間的差別有實質意義:舊指令是把自家 registry 包成 MCP 服務,新架構是單一伺服器統一代理 CLI 與所有已設定登錄,舊教學若還在教 registry:mcp,照抄會直接踩到已淘汰指令。

生態的分層也順著這條路長了出來。npm 上有獨立發布的 @shadcn/registry 套件(最新 0.2.1,10 月 27 日隨 CLI 同期更新),職責就是抓取、解析與安裝 registry 項目;換句話說,登錄的取用端已經抽成可獨立引用的一層,沒有鎖死在 CLI 的私有程式裡。想在自家工具或 CI 裡直接解析 registry 內容,這一層現在就拿得到。
四種用戶端的接法都寫在文件上。Claude Code 在專案裡跑 pnpm dlx shadcn@latest mcp init --client claude 後重啟即可;手動設定一律是 command: npx、args: ["shadcn@latest", "mcp"],差別主要在建哪個檔案:Claude Code 用專案 .mcp.json、Cursor 用 .cursor/mcp.json、VS Code 用 .vscode/mcp.json(給 Copilot 用,頂層鍵是 servers 而非 mcpServers),Codex 則要手改 ~/.codex/config.toml 加 [mcp_servers.shadcn] 段落,文件特別提醒 CLI 沒法自動更新 Codex 的設定檔。文件給的使用情境也很直白:對代理說 Find me a login form,它把這句話換成登錄查詢與安裝動作。出狀況時的官方建議包含清 npx 快取(npx clear-npx-cache)再重新啟用;代理能看到工具但叫不動時,先檢查這條。實際把代理接到元件安裝上的其他路徑,可以對照 Bencho 用 MCP 供應 React 區塊的做法。

接上之後,開發循環的變化可以用一個下午的實際節奏想:要一個登入表單,先讓代理搜尋登錄裡有什麼、用 view 看清單內容與依賴,確認要用哪個再下安裝,最後在 code review 看的是進到專案的那幾個檔案。與過去「把元件碼整段貼進提示詞、或讓代理憑印象生一份」相比,差別在每個動作都有可核對的中間產物:查詢結果看得見、要裝的檔案裝之前看得見、裝完的 diff 看得見。這也是把設計系統交給代理時,工程側真正需要的可審計性。
機制面上的原因,可以用官方文件驗證的三件事講完。shadcn 的模型是檔案進到你專案:官方對 registry 的定義是「程式碼的配送系統」,把元件、hooks、頁面、設定與其他檔案發送到任何專案,而且不限 React。元件碼躺在 src/components 這類你自己的目錄裡,代理讀得到、改得到,TypeScript 型別就在旁邊,這與封裝在 node_modules 黑盒子裡的傳統套件是兩種世界。依賴有 schema 承載:上一節的 registryDependencies 與 dependencies 宣告,讓「裝了 A 還缺什麼」變成可解析的資訊。搜尋與安裝還有統一介面:目錄加 MCP 把「找元件、看內容、裝進來」三個動作都變成代理可執行的工具呼叫,而不是靠提示詞複製貼上。
採用面上有個可核對的旁證:Lovable 官方文件的 changelog 在 Lovable 1.0 一節載明「加入 shadcn sidebar 元件支援」;同一份文件裡的範例工作區,coding guidelines 也寫著「Use shadcn/ui components when possible」與「Use Tailwind CSS for styling」。要誠實標註:後者是文件示範工作區指令寫法的範例,不是 Lovable 的全域規範;但 AI 建站工具圈與 shadcn 生態的重疊,從官方文件裡就能數得出來。專案本身的規模感同樣可核對:shadcn-ui/ui 儲存庫到 11 月 22 日有 128,692 顆星,前一天還有依賴更新進帳、同一週仍有功能 PR 併入,目錄的成長踩在這個活躍度上,不是無人維護側線的曇花一現。
view 看內容、看授權與價格、看對方的 GitHub 活躍度。registry:build 與 registry:mcp 在 4.0.0 已淘汰,網路上 2026 年 3 月前的教學照抄會踩到已棄用指令。未驗證的部分也交代:v0 是否預設輸出 shadcn/ui 架構,目前沒有可核對的第一手文件,不列入證據;MCP 伺服器實際裝起來的行為,未在本機實測,行為面以官方文件與 release notes 為準;目錄數字每天都在動,引用前以 shadcn 官方目錄與 release notes 的現況為準。
對個人開發者,動作最輕:裝好 MCP 伺服器,用自然語言搜尋與安裝,體感差距立刻有。對有設計系統的團隊,真正該判斷的是要不要建立「元件即登錄項目」的發布紀律:版本跟著 git、依賴寫進 schema、代理與工程師共用同一條安裝指令。做到這一步,代理亂生樣式的問題從「提示詞修不好」變成「登錄裡沒有」,後者是工程問題,前者永遠是玄學。
驗收標準也可以講得很具體:接上一個月後,打開新專案,讓代理生三個頁面,若生成結果的品牌色、圓角、間距與既有頁面一致,代表登錄與規則檔發揮作用;若代理還在自創樣式,先檢查它到底有沒有走 MCP 安裝,再檢查規則檔是否在登錄裡。失敗的跡象同樣明確:安裝指令常常失敗、登錄內容與文件對不起來,這時該整頓的是登錄內容與驗證流程;提示詞加長救不了這種失敗。593 個站三個星期的成長是市場訊號,訊號背後可持續的東西是那一套格式契約:schema 在、驗證在、CLI 會自動查,這才是目錄能一直長下去的原因。