Zipkit

台灣地址英譯與 3+3 郵遞區號查詢工具。

輸入中文地址，即時取得 UPU 格式英譯地址與六碼郵遞區號。純前端運作，所有資料皆為預先產生的靜態 JSON，無需後端 API。

Live -- zipkit.app

功能

• 縣市、鄉鎮市區、路街逐級聯動選擇
• 路街名稱支援模糊搜尋（cmdk combobox）
• 巷、弄、號、樓、室明細輸入
• 即時產出英譯地址（UPU 格式）
• 六碼郵遞區號（3+3）精確比對
• 台灣行政區互動地圖，點擊即可選取縣市與鄉鎮市區
• 地區可視化
• 一鍵複製結果
• 深色模式介面

技術棧

• Next.js 16 (App Router)
• React 19
• Tailwind CSS 4
• shadcn/ui 4 / mapcn
• MapLibre GL JS -- 台灣行政區地圖
• TypeScript 6
• pnpm workspace monorepo（apps/web 應用 + packages/core 核心邏輯）
• tsdown -- @zipkit/core 套件建置（Rolldown 驅動，輸出 ESM + 型別宣告）

快速開始

# 安裝依賴
pnpm install

# 啟動開發伺服器
pnpm dev

瀏覽器開啟 http://localhost:3000 即可使用。

指令

指令	說明
pnpm dev	啟動開發伺服器
pnpm build	正式環境建置
pnpm lint	執行 ESLint 檢查
pnpm typecheck	TypeScript 型別檢查
pnpm test	執行 @zipkit/core 單元測試 (Vitest)
pnpm format	格式化程式碼 (Prettier)
pnpm check	一次執行 typecheck + lint + format check
pnpm etl	從原始資料重新產生靜態 JSON

架構

資料流程（ETL）

原始郵政資料放置於 apps/web/scripts/raw/（不納入版本控制）。ETL 腳本（apps/web/scripts/etl.ts）處理兩份來源：

CityCountyData.json + AllData.json  -->  apps/web/public/data/base.json（縣市／鄉鎮市區索引）
                                         apps/web/public/data/roads/{zip3}.json（各區路街清單）

rall1.txt (CSV)                     -->  apps/web/public/data/zip-ranges/{zip3}.json（郵遞區號範圍規則）

• base.json 在建置時靜態匯入，包含所有縣市與鄉鎮市區
• roads/{zip3}.json 與 zip-ranges/{zip3}.json 於使用者選擇鄉鎮市區時按需載入並快取

郵遞區號比對

packages/core/src/lookup-zipcode.ts（@zipkit/core 套件）以特異性評分（specificity scoring）比對地址與郵遞區號範圍規則。條件越多（巷段、弄段、門牌範圍、單雙號、樓層）的規則分數越高，優先採用。支援門牌之號（如「5之1」）與樓層限制等進階比對。

狀態管理

apps/web/src/hooks/use-address-state.ts 以 useReducer 管理聯動表單狀態。選擇上層欄位時自動重設下層欄位。路街與郵遞區號資料透過 apps/web/src/lib/data-loader.ts 按需載入並快取於記憶體中。

專案結構

本專案為 pnpm workspace monorepo。

apps/
  web/                    # Next.js 應用（前端 + SSG 區頁）
    src/
      app/                # App Router 頁面
      components/         # UI 元件
      hooks/              # React hooks（地址狀態管理）
      lib/                # web 專屬工具（資料載入、地圖、slug）
    scripts/
      etl.ts              # ETL 資料轉換腳本
      raw/                # 原始郵政資料（不納入版本控制）
    public/
      data/               # 預先產生的靜態 JSON
packages/
  core/                   # @zipkit/core：地址核心邏輯（無框架依賴）
    src/
      lookup-zipcode.ts         # 3+3 郵遞區號特異性評分比對
      format-english-address.ts # UPU 格式英譯
      types.ts                  # 共用領域型別
    tsdown.config.ts            # tsdown 建置設定（輸出 ESM + .d.ts 至 dist/）
    dist/                       # 建置產物（不納入版本控制）

@zipkit/core 以 tsdown 建置為 dist/（ESM + 型別宣告），apps/web 消費編譯後的套件而非 TS 原始碼。凡會觸及 web 的指令（dev、build、lint、typecheck）皆會先建置 @zipkit/core，確保 dist/ 就緒。

資料來源

本專案使用以下第三方開源資料：

• 地址中英對照 -- donma/TaiwanAddressCityAreaRoadChineseEnglishJSON 提供台灣縣市、鄉鎮市區、路街的中英文對照資料（CityCountyData.json、AllData.json）。
• 3+3 郵遞區號範圍 -- 中華郵政 3+3 郵遞區號查詢 提供各地址區段對應的六碼郵遞區號範圍資料（rall1.txt）。

授權

本專案採用 MIT License 授權。