122 lines
3.7 KiB
Markdown
122 lines
3.7 KiB
Markdown
# 开发与测试
|
||
|
||
## 环境
|
||
|
||
- 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 配置。
|
||
|
||
## 首次准备
|
||
|
||
在项目根目录执行：
|
||
|
||
```bash
|
||
make build
|
||
make assets
|
||
```
|
||
|
||
make build 安装锁定的前端依赖、生成 web/dist，再构建 bin/clashweb；静态 Web 资源嵌入 Go 程序。make assets 下载指定 Mihomo 稳定版和大陆 MRS 规则，分别保存到 bin/mihomo 和 data/mihomo/rules。
|
||
|
||
资源已有时可复用：
|
||
|
||
```bash
|
||
cd web
|
||
npm run build
|
||
cd ..
|
||
CGO_ENABLED=0 go build -trimpath -ldflags='-s -w' -o bin/clashweb ./cmd/clashweb
|
||
```
|
||
|
||
Go 构建与测试依赖 web/dist 存在，首次克隆应先构建前端。前端构建完成后再执行 Go 构建，避免嵌入尚未生成的资源。
|
||
|
||
## 本地运行
|
||
|
||
终端一，生成配置并启动内核：
|
||
|
||
```bash
|
||
./bin/clashweb --mihomo ./bin/mihomo --init
|
||
./bin/mihomo -d ./data/mihomo -f ./data/mihomo/config.yaml
|
||
```
|
||
|
||
终端二，启动管理服务：
|
||
|
||
```bash
|
||
./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 后端运行，并在另一终端执行：
|
||
|
||
```bash
|
||
cd web
|
||
npm run dev
|
||
```
|
||
|
||
Vite 将 /api 转发至 http://127.0.0.1:8080。远程开发可用 SSH 转发访问管理服务：
|
||
|
||
```bash
|
||
ssh -N -L 8080:127.0.0.1:8080 USER@DEV_HOST
|
||
```
|
||
|
||
停止时在管理服务和内核终端分别按 Ctrl+C。本地 data/ 目录保留管理员、订阅和设置。
|
||
|
||
## 测试
|
||
|
||
前端构建已完成时可直接执行：
|
||
|
||
```bash
|
||
go test -race ./...
|
||
go vet ./...
|
||
cd web
|
||
npm run test
|
||
cd ..
|
||
```
|
||
|
||
真实内核集成测试：
|
||
|
||
```bash
|
||
CLASHWEB_TEST_MIHOMO_BIN="$PWD/bin/mihomo" \
|
||
CLASHWEB_TEST_RULES_DIR="$PWD/data/mihomo/rules" \
|
||
go test -race ./...
|
||
```
|
||
|
||
浏览器测试首次需要安装 Chromium：
|
||
|
||
```bash
|
||
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 构建环境执行：
|
||
|
||
```bash
|
||
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 或其他文件渠道传递，不作为源码提交。
|