Mage Go 语言构建工具教程

Mage 是一款使用 Go 语言编写的构建工具，旨在替代 Make。与 Makefile 使用特殊语法不同，Mage 直接使用 Go 代码定义构建目标，享受 Go 语言的类型安全、IDE 支持和丰富的标准库。Mage 没有引入任何自定义语法，你的构建脚本就是普通的 Go 代码。在搬瓦工 VPS 上使用 Mage 可以更好地管理 Go 项目的构建、测试和部署流程。

一、安装 Mage

1.1 使用 Go 安装

# 确保已安装 Go 环境
go install github.com/magefile/mage@latest

# 验证安装
mage --version

1.2 下载预编译二进制文件

wget https://github.com/magefile/mage/releases/latest/download/mage_linux_amd64.tar.gz
tar -xzf mage_linux_amd64.tar.gz
mv mage /usr/local/bin/
chmod +x /usr/local/bin/mage
rm mage_linux_amd64.tar.gz

二、创建 Magefile

在项目根目录创建 magefile.go 文件：

//go:build mage

package main

import (
    "fmt"
    "os"
    "os/exec"
    "time"

    "github.com/magefile/mage/mg"
    "github.com/magefile/mage/sh"
)

// Build 编译项目
func Build() error {
    fmt.Println("Building...")
    return sh.Run("go", "build", "-o", "bin/app", "./cmd/app")
}

// Test 运行测试
func Test() error {
    fmt.Println("Running tests...")
    return sh.Run("go", "test", "-v", "./...")
}

// Lint 运行代码检查
func Lint() error {
    fmt.Println("Running linter...")
    return sh.Run("golangci-lint", "run", "./...")
}

// Clean 清理构建产物
func Clean() error {
    fmt.Println("Cleaning...")
    return os.RemoveAll("bin")
}

// Default 设置默认目标
var Default = Build

2.1 运行 Mage 目标

# 列出所有可用目标
mage -l

# 运行默认目标（Build）
mage

# 运行指定目标
mage build
mage test
mage clean

三、高级用法

3.1 目标依赖

//go:build mage

package main

import "github.com/magefile/mage/mg"

// Deploy 部署应用（依赖 Build 和 Test）
func Deploy() error {
    mg.Deps(Build, Test)
    fmt.Println("Deploying...")
    return sh.Run("rsync", "-avz", "bin/app", "user@server:/opt/app/")
}

mg.Deps 会并行执行依赖目标，mg.SerialDeps 则按顺序执行。

3.2 带参数的目标

// BuildFor 为指定平台编译
func BuildFor(goos, goarch string) error {
    env := map[string]string{
        "GOOS":   goos,
        "GOARCH": goarch,
        "CGO_ENABLED": "0",
    }
    return sh.RunWith(env, "go", "build", "-o",
        fmt.Sprintf("bin/app-%s-%s", goos, goarch), "./cmd/app")
}

// BuildAll 编译所有平台
func BuildAll() error {
    platforms := []struct{ os, arch string }{
        {"linux", "amd64"},
        {"linux", "arm64"},
        {"darwin", "amd64"},
        {"darwin", "arm64"},
        {"windows", "amd64"},
    }
    for _, p := range platforms {
        if err := BuildFor(p.os, p.arch); err != nil {
            return err
        }
    }
    return nil
}

# 运行带参数的目标
mage buildFor linux amd64
mage buildAll

3.3 命名空间

type Docker mg.Namespace

// Build 构建 Docker 镜像
func (Docker) Build() error {
    return sh.Run("docker", "build", "-t", "myapp:latest", ".")
}

// Push 推送 Docker 镜像
func (Docker) Push() error {
    return sh.Run("docker", "push", "myapp:latest")
}

type DB mg.Namespace

// Migrate 运行数据库迁移
func (DB) Migrate() error {
    return sh.Run("go", "run", "./cmd/migrate", "up")
}

// Seed 填充测试数据
func (DB) Seed() error {
    return sh.Run("go", "run", "./cmd/seed")
}

# 使用命名空间
mage docker:build
mage docker:push
mage db:migrate
mage db:seed

四、实际项目示例

//go:build mage

package main

import (
    "fmt"
    "os"
    "runtime"
    "time"

    "github.com/magefile/mage/mg"
    "github.com/magefile/mage/sh"
)

var (
    version   = "dev"
    buildTime = time.Now().Format(time.RFC3339)
    goVersion = runtime.Version()
)

var ldflags = fmt.Sprintf(
    `-X main.version=%s -X main.buildTime=%s -X main.goVersion=%s`,
    version, buildTime, goVersion,
)

func Build() error {
    mg.Deps(Generate)
    fmt.Printf("Building version %s...\n", version)
    return sh.Run("go", "build", "-ldflags", ldflags, "-o", "bin/app", "./cmd/app")
}

func Generate() error {
    return sh.Run("go", "generate", "./...")
}

func Test() error {
    return sh.Run("go", "test", "-race", "-coverprofile=coverage.out", "./...")
}

func Coverage() error {
    mg.Deps(Test)
    return sh.Run("go", "tool", "cover", "-html=coverage.out", "-o", "coverage.html")
}

func Fmt() error {
    return sh.Run("gofmt", "-w", "-s", ".")
}

func Vet() error {
    return sh.Run("go", "vet", "./...")
}

// CI 运行完整的 CI 流水线
func CI() {
    mg.SerialDeps(Fmt, Vet, Test, Build)
}

func Clean() error {
    return sh.Run("rm", "-rf", "bin", "coverage.out", "coverage.html")
}

var Default = Build

五、在 CI/CD 中使用

# Gitea Actions Workflow
name: CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: '1.22'
      - run: go install github.com/magefile/mage@latest
      - run: mage ci

六、与 Make 的对比

语法：Mage 使用 Go 代码，Make 使用特殊语法。
类型安全：Mage 享有 Go 编译时检查，Make 没有。
跨平台：Mage 天然跨平台，Make 在 Windows 上需要额外工具。
IDE 支持：Mage 的 Go 代码可以获得完整的 IDE 支持。
学习成本：如果团队已经使用 Go，Mage 的学习成本几乎为零。

七、常见问题

Magefile 无法编译

确保文件顶部有正确的构建约束：

//go:build mage

依赖下载失败

go mod tidy
go mod download

总结

Mage 是 Go 项目的理想构建工具，用 Go 代码替代了复杂的 Makefile 语法。在搬瓦工 VPS 上配合 Gitea 和 CI/CD 使用，可以构建完整的自动化开发流程。选购搬瓦工 VPS 请参考全部方案，购买时使用优惠码 NODESEEK2026 可享受 6.77% 折扣。相关工具：Task 任务自动化。