3.7 KiB
开发与测试
环境
- Go 1.24+。
- Node.js 22.12+ 或 24+，npm。
- Python 3；Linux amd64 打包脚本的安全解压校验需要 Python 3.12+。
- Linux；正式代理服务与开发环境分开。
依赖版本由 go.mod、go.sum 和 web/package-lock.json 固定。Go 模块目录遵循开发机的 go env 配置。
首次准备
在项目根目录执行：
make build
make assets
make build 安装锁定的前端依赖、生成 web/dist，再构建 bin/clashweb；静态 Web 资源嵌入 Go 程序。make assets 下载指定 Mihomo 稳定版和大陆 MRS 规则，分别保存到 bin/mihomo 和 data/mihomo/rules。
资源已有时可复用：
cd web
npm run build
cd ..
CGO_ENABLED=0 go build -trimpath -ldflags='-s -w' -o bin/clashweb ./cmd/clashweb
Go 构建与测试依赖 web/dist 存在，首次克隆应先构建前端。前端构建完成后再执行 Go 构建，避免嵌入尚未生成的资源。
本地运行
终端一，生成配置并启动内核：
./bin/clashweb --mihomo ./bin/mihomo --init
./bin/mihomo -d ./data/mihomo -f ./data/mihomo/config.yaml
终端二，启动管理服务：
./bin/clashweb --mihomo ./bin/mihomo
访问 http://127.0.0.1:8080。首次设置令牌在启动日志中显示，管理员密码为 12–72 字节。已初始化的数据目录使用原管理员密码登录。
默认混合代理为 127.0.0.1:7890，DNS 为 127.0.0.1:1053，Mihomo 控制接口为 127.0.0.1:9090。开发时保持 TUN 关闭；IPv4 转发、防火墙和网关配置在目标 VM 上准备。
前端热更新时，保持 Go 后端运行，并在另一终端执行：
cd web
npm run dev
Vite 将 /api 转发至 http://127.0.0.1:8080。远程开发可用 SSH 转发访问管理服务：
ssh -N -L 8080:127.0.0.1:8080 USER@DEV_HOST
停止时在管理服务和内核终端分别按 Ctrl+C。本地 data/ 目录保留管理员、订阅和设置。
测试
前端构建已完成时可直接执行：
go test -race ./...
go vet ./...
cd web
npm run test
cd ..
真实内核集成测试：
CLASHWEB_TEST_MIHOMO_BIN="$PWD/bin/mihomo" \
CLASHWEB_TEST_RULES_DIR="$PWD/data/mihomo/rules" \
go test -race ./...
浏览器测试首次需要安装 Chromium：
cd web
npx playwright install chromium
cd ..
python3 scripts/test-e2e.py
E2E 使用临时数据库、本地订阅夹具、真实后端和 Mihomo；管理服务监听 127.0.0.1:18080，需要 9090/7890/1053 空闲。检测到端口占用时终止，结束后清理测试进程和临时数据库。常用网站响应在浏览器测试中使用夹具。
截图写入 .cache/screenshots，测试报告写入 web/test-results，均不提交到 Git。无需重装依赖时，直接使用以上命令；make test、make integration、make e2e 会先重新准备前端依赖。
配置与提交范围
- bin/：本地生成的管理程序和下载的内核。
- data/：SQLite、订阅、控制密钥、内核配置和规则。
- web/dist/：嵌入 Go 程序的前端输出。
- web/node_modules/：前端开发依赖。
- .cache/、测试报告和压缩包：过程或分发产物。
这些目录和文件由 .gitignore 排除。只提交源码、锁文件、测试、部署脚本和维护文档。
打包
在 Linux amd64 构建环境执行：
GOOS=linux GOARCH=amd64 GOAMD64=v1 CGO_ENABLED=0 \
go build -trimpath -ldflags='-s -w' -o bin/clashweb ./cmd/clashweb
python3 scripts/package.py
脚本只使用现有程序与规则生成完整安装包和管理更新包，附文件清单和 SHA-256，执行解压校验与隔离初始化，不包含开发数据库或订阅。分发包通过 Gitea Release 或其他文件渠道传递，不作为源码提交。