Development

English | 简体中文

Repository layout

The source is organized to keep the Go application buildable with the normal go build . command:

main.go                    Root executable entry point
internal/app/              Panel backend and Go tests
internal/mihomoconvert/    Mihomo sharing-link converter
web/                       Embedded HTML, CSS, JavaScript, and assets
tests/                     Browser regression scripts
scripts/                   Local run/build/release/management scripts
deploy/                    systemd and OpenRC service definitions
install.sh                 GitHub one-line Linux installer

The backend remains one internal Go package so its unexported validation and rendering helpers can be tested together. The frontend is a separate embedded package.

Local prerequisites

• Go 1.24 or newer
• Node.js for optional browser tests
• Mihomo executable for local runtime testing
• Playwright for the browser regression scripts

Run the application during development:

.\scripts\run.ps1

or:

./scripts/run.sh

Go tests and vet

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

The main application tests cover YAML compilation, subscriptions, WARP, Multi-control, inbound synchronization, cross-panel aggregation, migration, and settings validation.

For race testing of the networking and CLI paths:

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

Build scripts

Build Windows, a Linux amd64 binary, and run the Go test suite:

.\scripts\build.ps1

Build all published Linux Release archives:

.\scripts\build-release.ps1

The release script emits:

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

Each archive contains one executable named m-ui-linux-<architecture>.

Version injection

Builds accept MUI_VERSION. If it is not set, the scripts use a tag pointing at HEAD; otherwise they fall back to dev-<short-commit>. The linker flag is:

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

The value is returned by m-ui version and is also used in panel state, backup manifests, log messages, and the HTTP User-Agent.

GitHub Actions release flow

The recommended workflow is triggered by tags matching v*. It should:

1. Check out the repository with full history.
2. Set up Go from go.mod.
3. Validate the tag, run go test ./..., and run go vet ./....
4. Build the seven Linux architectures with CGO_ENABLED=0.
5. Inject main.version using GITHUB_REF_NAME.
6. Verify archive contents and the amd64 version output.
7. Create a GitHub Release using contents: write.

Use annotated semantic tags such as:

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

Prerelease tags such as v0.2.0-rc.1 should be marked as prereleases. Do not reuse an existing public version.

Frontend tests

The scripts under tests/ use Playwright to exercise Mihomo Basics, Outbound YAML editing, Multi-control, and WARP flows. Install the project test dependency in your own development environment and run the scripts with the test server running. These dependencies are not needed by the Linux runtime binary.

Contribution guidelines

When changing a protocol field:

1. Confirm the corresponding Mihomo version behavior.
2. Update the Go model, normalization, YAML rendering, share-link generation, and UI field together.
3. Add a focused Go regression test.
4. Check that unsupported fields are not accidentally emitted to the core.
5. Run go test ./... and go vet ./....
6. Update the relevant Wiki page.

Never commit data/, generated binaries, build caches, certificates, private keys, pairing state, or local logs.