feat: webui 支持 pnpm 以及环境变量

README.MD

@@ -306,6 +306,8 @@ go run ./cmd/ds2api
 
 > **WebUI 自动构建**：本地首次启动时，若 `static/admin` 不存在，会自动尝试执行 `npm ci`（仅在缺少依赖时）和 `npm run build -- --outDir static/admin --emptyOutDir`（需要本机有 Node.js 和 npm）。你也可以手动构建：`./scripts/build-webui.sh`
 
+> **WebUI 开发服务器**：如需单独启动前端开发服务器（根目录: `npm run dev --prefix webui`；webui/ 目录: `npm run dev` 或 `pnpm run dev`），Vite 代理后端地址由 `webui/.env` 中的 `VITE_API_BASE_URL` 控制。
+
 ## 配置说明
 
 `README` 只保留快速入口，完整字段请以 [config.example.json](config.example.json) 为模板，并参考 [部署指南](docs/DEPLOY.md#0-前置要求) 与 [API 配置最佳实践](API.md#配置最佳实践)。
@@ -415,7 +417,12 @@ go run ./cmd/ds2api
 ./scripts/lint.sh
 ./tests/scripts/check-refactor-line-gate.sh
 ./tests/scripts/run-unit-all.sh
+# 从仓库根目录
 npm run build --prefix webui
+# 或在 webui 目录下
+npm run build
+# 或
+pnpm run build
 
 # 端到端全链路测试（真实账号，生成完整请求/响应日志）
 ./tests/scripts/run-live.sh

README.en.md

@@ -294,6 +294,8 @@ The server actually binds to `0.0.0.0:5001`, so devices on the same LAN can usua
 
 > **WebUI auto-build**: On first local startup, if `static/admin` is missing, DS2API will auto-run `npm ci` (only when dependencies are missing) and `npm run build -- --outDir static/admin --emptyOutDir` (requires Node.js). You can also build manually: `./scripts/build-webui.sh`
 
+> **WebUI dev server**: If you want to start the frontend dev server separately (repo root: `npm run dev --prefix webui`; in webui/: `npm run dev` or `pnpm run dev`), the Vite proxy target is controlled by `VITE_API_BASE_URL` in `webui/.env`.
+
 ## Configuration
 
 `README` keeps only the onboarding path. Use [config.example.json](config.example.json) as the field template, and see the [deployment guide](docs/DEPLOY.en.md#0-prerequisites) plus [API configuration notes](API.en.md#configuration-best-practice) for full details.
@@ -399,7 +401,14 @@ Quick commands:
 ./scripts/lint.sh
 ./tests/scripts/check-refactor-line-gate.sh
 ./tests/scripts/run-unit-all.sh
+# From repo root
 npm run build --prefix webui
+# Or in webui/
+npm run build
+# Or
+pnpm run build
+
+
 
 # Live end-to-end tests (real accounts, full request/response logs)
 ./tests/scripts/run-live.sh

docs/CONTRIBUTING.en.md

@@ -36,10 +36,16 @@ go run ./cmd/ds2api
 cd webui
 
 # 2. Install dependencies
+# npm
 npm ci
+# or pnpm
+pnpm install
 
 # 3. Start dev server (hot reload)
+# npm (already in webui/)
 npm run dev
+# or pnpm
+pnpm run dev
 # Default: http://localhost:5173, auto-proxies API to backend
 # host: 0.0.0.0 is not configured, so LAN access is not enabled by default
 ```
@@ -91,7 +97,10 @@ Manually build WebUI to `static/admin/`:
 ./scripts/lint.sh
 ./tests/scripts/check-refactor-line-gate.sh
 ./tests/scripts/run-unit-all.sh
+# From repo root
 npm run build --prefix webui
+# Or in webui/
+npm run build or pnpm run build
 
 # End-to-end live tests (real accounts; recommended for releases or high-risk changes)
 ./tests/scripts/run-live.sh

docs/CONTRIBUTING.md

@@ -36,10 +36,16 @@ go run ./cmd/ds2api
 cd webui
 
 # 2. 安装依赖
+# npm
 npm ci
+# 或 pnpm
+pnpm install
 
 # 3. 启动开发服务器（热更新）
+# npm（已在 webui/ 目录下）
 npm run dev
+# 或 pnpm
+pnpm run dev
 # 默认监听 http://localhost:5173，自动代理 API 到后端
 # 当前未配置 host: 0.0.0.0，因此默认不对局域网开放
 ```
@@ -91,7 +97,10 @@ I/O 类清理调用（如 `Close`、`Flush`、`Sync`）的错误不要直接忽
 ./scripts/lint.sh
 ./tests/scripts/check-refactor-line-gate.sh
 ./tests/scripts/run-unit-all.sh
+# 从仓库根目录
 npm run build --prefix webui
+# 或在 webui 目录下
+npm run build 或 pnpm run build
 
 # 端到端全链路测试（真实账号，发布或高风险改动时建议执行）
 ./tests/scripts/run-live.sh

docs/DEPLOY.en.md

@@ -421,6 +421,9 @@ Or step by step:
 cd webui
 npm ci
 npm run build
+# or pnpm
+pnpm install
+pnpm run build
 # Output goes to static/admin/
 ```
 

docs/DEPLOY.md

@@ -431,6 +431,9 @@ go run ./cmd/ds2api
 cd webui
 npm ci
 npm run build
+# 或 pnpm
+pnpm install
+pnpm run build
 # 产物输出到 static/admin/
 ```
 

docs/DEVELOPMENT.md

@@ -13,10 +13,20 @@
 go run ./cmd/ds2api
 
 # WebUI 开发服务器
+# 从仓库根目录
 npm run dev --prefix webui
+# 或在 webui 目录下
+npm run dev
+# 或
+pnpm run dev
 
 # WebUI 生产构建
+# 从仓库根目录
 npm run build --prefix webui
+# 或在 webui 目录下
+npm run build
+# 或
+pnpm run build
 ```
 
 PR 前固定门禁：
@@ -25,7 +35,12 @@ PR 前固定门禁：
 ./scripts/lint.sh
 ./tests/scripts/check-refactor-line-gate.sh
 ./tests/scripts/run-unit-all.sh
+# 从仓库根目录
 npm run build --prefix webui
+# 或在 webui 目录下
+npm run build
+# 或
+pnpm run build
 ```
 
 修改 Go 文件后先运行：
@@ -94,7 +109,10 @@ go test ./internal/<package> -count=1
 前端改动：
 
 ```bash
+# 从仓库根目录
 npm run build --prefix webui
+# 或在 webui 目录下
+npm run build 或 pnpm run build
 ```
 
 高风险协议或流式改动：

docs/TESTING.md

@@ -29,7 +29,13 @@ Node 单元测试脚本会先做 `node --check` 语法门禁，再以 `--test-co
 ./scripts/lint.sh
 ./tests/scripts/check-refactor-line-gate.sh
 ./tests/scripts/run-unit-all.sh
+# 从仓库根目录
 npm run build --prefix webui
+
+# 或在 webui 目录下
+npm run build
+# 或
+pnpm run build
 ```
 
 说明：

webui/.env.example

@@ -0,0 +1,12 @@
+## 这个文件只作为示例，修改不会生效
+## 如果需要更改环境变量 请在前端项目webui根目录下创建 .env 文件，并添加 VITE_API_BASE_URL 变量
+## 添加后端访问地址 例如：VITE_API_BASE_URL=http://example.com:5001
+
+# Vite 开发时代理目标后端地址
+# 默认值: http://localhost:5001
+
+# 本地开发 (Go 后端直接运行或 Docker 部署)
+VITE_API_BASE_URL=http://localhost:5001
+
+# 线上服务器 (调试远端后端，按需取消注释并修改)
+# VITE_API_BASE_URL=http://example.com:5001