本地開發 | SubLane

環境

應用倉庫需要 Go 1.26+、Node.js 24 與 packageManager 指定的 pnpm 9.12.2。安裝腳本的合成發布測試需要 jq。 Docker 僅用於容器驗證，並非本地開發的前提。

以下命令在 SubLane 應用倉庫根目錄 執行，不是在獨立官網的 website/ 目錄。

安装依赖并启动应用开发环境

make setup
make dev

常用命令

命令	用途
`make dev`	同時啟動 Air 後端自動重載與 Vite 前端 HMR
`make dev-api`、`make dev-web`	分別啟動帶有 Air 自動重載的後端與 Vite
`make build`	構建前端並嵌入 `bin/sublane`
`make generate`	根據 SQL 重新產生 sqlc 查詢程式碼
`make generate-check`	檢查生成結果漂移
`make test`	腳本、Go race 與前端測試
`make lint`	格式、vet、型別與 lint
`make check`	所有檢查及生產構建
`make clean`	清理建置輸出，不刪除資料庫與依賴

修改 Go 原始碼、內嵌 SQL、go.mod 或 go.sum 後，Air 自動重新編譯並重新啟動後端。前端由 Vite 提供 HMR，不觸發後端重新啟動。前端連接埠佔用時使用 make dev WEB_PORT=5174。

Makefile 透過 go run 使用固定版 Air v1.67.4，首次運行會下載並編譯，無需全域安裝，也不會把 Air 依賴加入應用程式模組。.air.toml 將臨時建置放在已忽略的 bin/air/ 下，重啟前為後端保留最多十秒的正常關閉時間。開發後端與生產建置一樣關閉 CGO，避免 macOS C 連結器的最低系統版本不一致警告；race 測試繼續使用 CGO。

環境變數

複製 .env.example 不會自動啟用變量，需要 shell 導出或命令前綴：

覆盖开发运行参数

SUBLANE_LOG_LEVEL=debug make dev
SUBLANE_ADDR=127.0.0.1:9090 ./bin/sublane

WEB_PORT 只修改前端連接埠。後端預設監聽 127.0.0.1:8080，Vite 自動讀取與後端相同的 SUBLANE_ADDR。如果已有 Docker 實例或其他進程佔用 8080，可使用獨立後端連接埠：

使用独立开发后端端口

SUBLANE_ADDR=127.0.0.1:9090 make dev WEB_PORT=5174

make dev 會在啟動 Air 與 Vite 前檢查後端位址，位址已被佔用時直接報錯，避免後端監聽失敗但 Air 仍運作時，新前端誤連到其他或舊版服務。分別運行 make dev-api 和 make dev-web 時，兩個命令需傳入相同的 SUBLANE_ADDR。

代理保留 Host（changeOrigin: false）以滿足同源認證。開發初始化使用空的暫存資料目錄與合成帳號，不能刪除工作實例資料庫來重設環境。

測試要求

聚焦后端与前端测试

go test ./internal/server -run TestRoutesAndAssetBoundary -count=1
pnpm --dir web test src/App.test.tsx

只用合成憑證、模擬上游和臨時資料庫。行為改動先補失敗測試，再實現並執行相關檢查。瀏覽器還需檢查桌面與窄螢幕、直接路由刷新、語言切換、主題和後端斷連狀態。

保留 internal/storage/migrations/ 中的既有遷移，包括 001_schema.sql；後續結構變更新增依序執行的增量遷移，並更新 internal/storage/queries/ 中的具名查詢。啟動時會為受支援的資料庫執行缺少的遷移；包含 001_settings.sql 的早期不相容結構會被拒絕。執行 make generate、make generate-check 及相關儲存測試；sqlc 驗證結構，不負責遷移運行中的資料庫。真實服務商驗收使用獨立授權的測試帳號，不使用正式環境資料作為測試樣本。

官網開發

官網在相鄰的 website/ 目錄維護，使用 Next.js 與 Fumadocs。英文內容位於 content/docs/，其他語言位於 content/<locale>/，同名檔案對應同一主題。介面、官網和文件均支援 11 種語言；新增翻譯由機器輔助生成，需要母語使用者進一步校對。命令、程式碼、連結和插值變數必須保持不變。官網使用自身的 package.json，獨立執行 pnpm dev --port 3100、pnpm test、pnpm test:e2e 和 pnpm build。