# 开发与测试

## 环境

- 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 或其他文件渠道传递，不作为源码提交。