貢獻指南

歡迎為 lh-ui-plus 貢獻程式碼！本文件提供詳細的貢獻流程。

前提條件

• Node.js 18+
• pnpm 安裝依賴
• Git 基本操作

安裝依賴

git clone https://github.com/lhgb-top/lh-ui-plus.git
cd lh-ui-plus
pnpm install

開發流程

1. 啟動開發伺服器

pnpm dev

2. 執行測試

pnpm test:unit      # Core 層單元測試
pnpm test:components  # 元件整合測試
pnpm test            # 全部測試

3. 類型檢查

pnpm typecheck

4. 程式碼檢查

pnpm lint
pnpm lint:fix       # 自動修復

5. 建構

pnpm build

6. 檢視文件

pnpm docs:dev

新增元件

完整流程請參考 AGENTS.md §"Adding or changing a component"。

簡要步驟：

1. @lh-ui/share 的 src/core/<name>/ — 核心邏輯 + 單元測試（在 share 儲存庫完成，本儲存庫以 npm 依賴消費）
2. packages/components/<name>/ — Vue 元件封裝
3. packages/components/index.ts — 註冊到 lhComponents
4. src/index.ts — 更新出口
5. tests/unit/components-registry.spec.ts — 更新期望陣列
6. tests/components/<name>.spec.ts — 元件測試
7. docs/components/<name>.md — 文件頁面
8. docs/.vitepress/config.ts — 側邊欄導覽

驗證命令：

pnpm lint          # 0 errors, 0 warnings
pnpm typecheck     # 無輸出
pnpm vitest run    # 全部用例通過
pnpm docs:build    # 通過

文件站部署

文件站的部署路徑由 docs/.env.production 集中設定（單一資料來源），生產建構直接：

pnpm docs:build

環境變數	說明	預設值	範例
DOCS_BASE	站臺 base 路徑，首尾必須帶斜槓	/	/lhui/vue3/
DOCS_HOSTNAME	站臺規範網域，用於 sitemap 與 SEO meta	https://www.lhgb.top	https://your-site.com

這兩個變數會同時作用於資源路徑、sitemap、og:url 等 SEO 標籤，以及建構末尾重新產生的 robots.txt。

為什麼放在 .env 而不是行內變數：Vite 內建的 env 載入發生在使用者 config 求值之後，docs/.vitepress/config.ts 必須顯式 loadEnv 才能在生產建構時讀到這些值；此外 Windows Git Bash 的 MSYS 會把行內的 DOCS_BASE=/lhui/vue3/ 自動轉成本地絕對路徑。臨時覆寫仍可用行內變數（DOCS_BASE=/xxx/ pnpm docs:build），但日常部署改 .env.production 更穩妥。

統一發佈前綴約定

風默門戶（www.lhgb.top）的 LH-UI 元件庫導覽頁（/ui）按 /lhui/{庫名}/ 統一約定各元件庫文件站的部署路徑，不與框架名綁定。本庫（Vue 3 版）部署在 /lhui/vue3/（已寫入 docs/.env.production），生產建構命令：

pnpm docs:build

建構產物上傳到伺服器 /home/webuser/nginx/lh-ui/vue3/（Nginx location 片段的權威參考副本見 家族 docs/部署/nginx-lhui.conf.md，線上真身在伺服器 /etc/nginx/conf.d/nginx.conf）。家族八站已全部按此約定部署：

儲存庫	base	alias 目錄	cleanUrls
lh-ui-plus（本庫）	/lhui/vue3/	/home/webuser/nginx/lh-ui/vue3/	否
lh-ui-vue2	/lhui/vue2/	/home/webuser/nginx/lh-ui/vue2/	否（VuePress 1.x）
lh-ui-react	/lhui/react/	/home/webuser/nginx/lh-ui/react/	否
lh-ui-uniapp	/lhui/uniapp/	/home/webuser/nginx/lh-ui/uniapp/	是
lh-ui-android	/lhui/android/	/home/webuser/nginx/lh-ui/android/	是
lh-ui-ios	/lhui/ios/	/home/webuser/nginx/lh-ui/ios/	是
lh-ui-harmony	/lhui/harmony/	/home/webuser/nginx/lh-ui/harmony/	是
lh-ui-windows	/lhui/windows/	/home/webuser/nginx/lh-ui/windows/	是

原生血脈四站（android / ios / harmony / windows）是 VitePress 站內嵌靜態 HTML 模擬器，部署方式與 web 血脈四站完全相同。新增庫仍按 /lhui/{庫名}/ 各自擴展 location 與 .env.production。

cleanUrls 站（uniapp 及原生四端）的 Nginx try_files 必須含 $uri.html，否則無後綴 URL 取不到預先繪製的 .html；非 cleanUrls 站不需要這一段。詳見參考副本的「三條契約」節。

程式碼規範

• CSS 類別使用 lh- 前綴（如 lh-button__text--primary）
• Composables 必須使用 Lh 前綴（如 useLhConfigProvider）
• 常數物件必須使用全大寫蛇形命名（如 LH_TYPES_CONST）
• 路徑別名：~/* → packages/*（本儲存庫）；框架無關邏輯與樣式在 @lh-ui/share，走 npm 子路徑匯入（@lh-ui/share/core/*、@lh-ui/share/styles/*）
• 格式化：單引號、無分號、2 空格縮排、100 字元行寬

提交規範

feat: 新增 Select 下拉選擇組件
fix: 修復 Input 焦點丟失問題
docs: 更新安裝文檔
test: 補充 Button 邊界測試
refactor: 重構 ConfigProvider 響應式邏輯

AI 輔助約定

專案由 AI agent 輔助維護。驗證命令由使用者手動執行，AI 不會自動執行測試/建構。