Development.zh_CN

English | 简体中文

仓库结构

源码结构确保仍可以使用普通的 go build .：

main.go                    根目录程序入口
internal/app/              面板后端和 Go 测试
internal/mihomoconvert/    Mihomo 分享链接转换器
web/                       嵌入的 HTML、CSS、JavaScript 和静态资源
tests/                     浏览器回归脚本
scripts/                   本地运行、构建、Release 和管理脚本
deploy/                    systemd 和 OpenRC 服务定义
install.sh                 GitHub 一键安装入口

后端保留为一个 internal Go package，使未导出的校验、渲染和业务帮助函数能够一起测试。前端作为独立 package 嵌入二进制。

本地依赖

• Go 1.24 或更高版本
• 可选浏览器测试所需的 Node.js
• 本地运行测试所需的 Mihomo 可执行文件
• 浏览器回归脚本所需的 Playwright

开发时运行：

.\scripts\run.ps1

或：

./scripts/run.sh

Go 测试和 Vet

go test ./...
go vet ./...

主要应用测试覆盖 YAML 编译、订阅、WARP、Multi-control、Inbound Sync、跨面板聚合、数据迁移和 Settings 校验。

对网络和 CLI 关键路径执行竞态测试：

go test -race ./... -run 'TestConfigureCLI|TestCrossSubscription|TestInboundSync|TestMesh'

构建脚本

运行 Go 测试并构建 Windows 和 Linux amd64：

.\scripts\build.ps1

构建全部 Linux Release 压缩包：

.\scripts\build-release.ps1

Release 脚本生成：

m-ui-linux-386.tar.gz
m-ui-linux-amd64.tar.gz
m-ui-linux-arm64.tar.gz
m-ui-linux-armv5.tar.gz
m-ui-linux-armv6.tar.gz
m-ui-linux-armv7.tar.gz
m-ui-linux-s390x.tar.gz

每个压缩包只有一个名为 m-ui-linux-<architecture> 的可执行文件。

版本注入

构建支持 MUI_VERSION。未设置时，脚本优先使用指向 HEAD 的 tag，否则回退到 dev-<short-commit>。链接参数是：

-ldflags="-s -w -X main.version=v0.2.0"

该值由 m-ui version 返回，也会用于面板状态、备份 manifest、日志和 HTTP User-Agent。

GitHub Actions Release 流程

建议工作流监听 v* tag，并执行：

1. 使用完整历史 checkout 仓库。
2. 根据 go.mod 安装 Go。
3. 校验 tag，运行 go test ./... 和 go vet ./...。
4. 设置 CGO_ENABLED=0，构建 7 个 Linux 架构。
5. 用 GITHUB_REF_NAME 注入 main.version。
6. 校验压缩包内容和 amd64 的 version 输出。
7. 使用 contents: write 创建 GitHub Release。

使用语义化 annotated tag：

git tag -a v0.1.0 -m "m-ui v0.1.0"
git push origin v0.1.0

v0.2.0-rc.1 等测试 tag 应标记为 prerelease。不要重复使用已经公开的版本号。

前端测试

tests/ 中的脚本使用 Playwright 测试 Mihomo Basics、Outbound YAML 编辑、Multi-control 和 WARP。请在开发环境中安装测试依赖，并在测试服务器运行时执行脚本；Linux 运行二进制本身不需要这些依赖。

贡献说明

修改协议字段时：

1. 确认对应 Mihomo 版本的真实行为。
2. 同时更新 Go model、规范化、YAML 渲染、分享链接和 UI 字段。
3. 添加针对性的 Go 回归测试。
4. 确认没有把不受支持的字段误写入核心配置。
5. 运行 go test ./... 和 go vet ./...。
6. 更新对应 Wiki 页面。

不要提交 data/、生成的二进制、构建缓存、证书、私钥、Peer 身份状态或本地日志。