diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index a050fcd..912b245 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -22,6 +22,17 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
+      # 前端 dist 被 pyproject.toml 的 force-include 引用，pip install -e .
+      # 要求它存在。先构建前端（type-check + vite build）。
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: web-ui/package-lock.json
+      - run: npm ci
+        working-directory: web-ui
+      - run: npm run build
+        working-directory: web-ui
       - run: pip install -e ".[dev]"
       - run: pip install -r requirements-dev.txt
       - run: python -m pytest tests/unit/ -v --tb=short --cov src/easy_tdx --cov-fail-under=60
@@ -35,6 +46,16 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: "3.13"
+      # 同 test job：force-include 要求 web-ui/dist 存在。
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: web-ui/package-lock.json
+      - run: npm ci
+        working-directory: web-ui
+      - run: npm run build
+        working-directory: web-ui
       - run: pip install -e ".[dev,web]"
       - run: mypy src/
 
diff --git a/pyproject.toml b/pyproject.toml
index ca6e943..5748a6b 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -30,8 +30,8 @@ artifacts = [
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/easy_tdx"]
-# 前端 dist 映射到包内 easy_tdx/web/dist/，让 pip install 后开箱即用 UI。
-# 运行时由 _resolve_web_dist_dir 第 4 级探测找到。
+# 前端 dist 映射到包内 easy_tdx/web/dist/。CI（ci.yml）、publish（publish.yml）
+# 和 release（release.yml）都会在 pip install / build 前先 npm run build。
 force-include = { "web-ui/dist" = "easy_tdx/web/dist" }
 
 [tool.mypy]