Go Modules 基础使用 #

快速开始 #

创建新项目 #

bash

# 1. 创建项目目录（任意位置）
mkdir myproject
cd myproject

# 2. 初始化模块
go mod init myproject

# 输出：
# go: creating new go.mod: module myproject

# 3. 查看生成的文件
cat go.mod

生成的 go.mod 文件：

module myproject

go 1.21

模块命名规范 #

bash

# 个人项目
go mod init github.com/username/project

# 组织项目
go mod init github.com/company/project

# 简单项目（本地开发）
go mod init myproject

# 私有仓库
go mod init gitlab.company.com/team/project

第一个示例 #

创建主程序 #

bash

# 创建 main.go
cat > main.go << 'EOF'
package main

import (
    "fmt"
    "github.com/gin-gonic/gin"
)

func main() {
    r := gin.Default()
    r.GET("/", func(c *gin.Context) {
        c.JSON(200, gin.H{
            "message": "Hello, Go Modules!",
        })
    })
    
    fmt.Println("Server starting on :8080")
    r.Run(":8080")
}
EOF

自动下载依赖 #

bash

# 方式一：运行时自动下载
go run main.go

# 方式二：手动下载
go mod tidy
go mod download

# 方式三：构建时自动处理
go build

查看依赖变化 #

bash

# go.mod 更新后
cat go.mod

module myproject

go 1.21

require github.com/gin-gonic/gin v1.9.1

bash

# go.sum 自动生成
cat go.sum

text

github.com/gin-gonic/gin v1.9.1 h1:4idEAncQnU5cB7BeOkPtxjfCSye0AAm1R0RVIqFPSHk=
github.com/gin-gonic/gin v1.9.1/go.mod h1:hPrL6YRBqCtAI1IJFI4BYmqfvzDv3w==
github.com/go-playground/locales v0.14.1 h1:2WGlxRO+E8f4Ajv3IvP+K7Q7k1zCwP7UO7f0p7gN1Q=
...

go.mod 文件详解 #

基本结构 #

module github.com/myuser/myproject  // 模块路径

go 1.21  // Go 版本要求

require (  // 直接依赖
    github.com/gin-gonic/gin v1.9.1
    golang.org/x/text v0.14.0
)

require (  // 间接依赖
    github.com/bytedance/sonic v1.9.1 // indirect
    github.com/gabriel-vasile/mimetype v1.4.2 // indirect
)

replace (  // 模块替换
    github.com/old/pkg => github.com/new/pkg v1.0.0
)

exclude (  // 排除版本
    github.com/problematic/pkg v1.0.0
)

retract (  // 撤回版本
    v1.0.0
    v1.0.1
)

module 指令 #

// 模块路径定义
module github.com/myuser/myproject

// 子目录包的导入路径
// myproject/mypackage
import "github.com/myuser/myproject/mypackage"

go 指令 #

// 指定 Go 版本
go 1.21

// Go 1.21+ 还会设置兼容性
go 1.21.0  // 精确版本

require 指令 #

// 单行格式
require github.com/gin-gonic/gin v1.9.1

// 块格式
require (
    github.com/gin-gonic/gin v1.9.1
    golang.org/x/text v0.14.0
)

// 间接依赖标记
require (
    github.com/bytedance/sonic v1.9.1 // indirect
)

常用命令速查 #

模块初始化 #

bash

# 初始化新模块
go mod init <module-path>

# 示例
go mod init github.com/myuser/myproject
go mod init myproject

依赖管理 #

bash

# 整理依赖（添加缺失的，移除多余的）
go mod tidy

# 下载依赖到缓存
go mod download

# 验证依赖
go mod verify

# 查看依赖
go mod why <package>
go mod why github.com/gin-gonic/gin

依赖查看 #

bash

# 查看所有依赖
go list -m all

# 查看依赖图
go mod graph

# 查看特定模块信息
go list -m -versions github.com/gin-gonic/gin
go list -m -json github.com/gin-gonic/gin

Vendor 模式 #

bash

# 创建 vendor 目录
go mod vendor

# 使用 vendor 构建
go build -mod=vendor

# 使用 vendor 运行
go run -mod=vendor main.go

添加依赖 #

方式一：代码导入 + tidy #

bash

# 1. 在代码中添加 import
import "github.com/gin-gonic/gin"

# 2. 运行 tidy 自动添加
go mod tidy

方式二：使用 go get #

bash

# 添加最新版本
go get github.com/gin-gonic/gin

# 添加指定版本
go get github.com/gin-gonic/gin@v1.9.1

# 添加特定分支/标签
go get github.com/gin-gonic/gin@latest
go get github.com/gin-gonic/gin@main
go get github.com/gin-gonic/gin@v1

# 添加并更新到最新
go get -u github.com/gin-gonic/gin
go get -u=patch github.com/gin-gonic/gin

方式三：手动编辑 go.mod #

// 编辑 go.mod
require (
    github.com/gin-gonic/gin v1.9.1
)

// 然后运行
go mod download

更新依赖 #

更新单个依赖 #

bash

# 更新到最新版本
go get github.com/gin-gonic/gin@latest

# 更新到特定版本
go get github.com/gin-gonic/gin@v1.9.1

# 更新补丁版本
go get -u=patch github.com/gin-gonic/gin

更新所有依赖 #

bash

# 更新所有直接依赖
go get -u

# 更新所有依赖（包括间接）
go get -u=patch

# 整理依赖
go mod tidy

查看可更新依赖 #

bash

# 列出所有依赖
go list -u -m all

# 输出示例
github.com/gin-gonic/gin v1.9.0 [v1.9.1]
golang.org/x/text v0.13.0 [v0.14.0]

移除依赖 #

移除未使用的依赖 #

bash

# 自动移除未使用的依赖
go mod tidy

手动移除 #

bash

# 从 go.mod 移除
# 1. 编辑 go.mod，删除对应行
# 2. 运行 tidy
go mod tidy

go.sum 文件 #

文件格式 #

text

# 格式：模块路径 版本 hash类型=hash值
github.com/gin-gonic/gin v1.9.1 h1:4idEAncQnU5cB7BeOkPtxjfCSye0AAm1R0RVIqFPSHk=
github.com/gin-gonic/gin v1.9.1/go.mod h1:hPrL6YRBqCtAI1IJFI4BYmqfvzDv3w==

hash 类型 #

hash 类型	说明
h1:	模块 zip 文件的 SHA-256 哈希
/go.mod	go.mod 文件的哈希

为什么需要 go.sum #

完整性验证：确保下载的依赖未被篡改
一致性保证：确保团队成员使用相同的依赖
安全性：防止中间人攻击

是否提交 go.sum #

必须提交！ go.sum 应该纳入版本控制：

bash

# 正确做法
git add go.mod go.sum
git commit -m "update dependencies"

项目结构示例 #

单模块项目 #

text

myproject/
├── go.mod
├── go.sum
├── main.go
├── cmd/
│   └── cli/
│       └── main.go
├── pkg/
│   ├── utils/
│   │   └── utils.go
│   └── api/
│       └── api.go
├── internal/
│   └── config/
│       └── config.go
└── vendor/        # 可选
    └── ...

导入内部包 #

// main.go
package main

import (
    "myproject/pkg/utils"
    "myproject/internal/config"
)

func main() {
    utils.DoSomething()
    config.Load()
}

环境变量配置 #

常用环境变量 #

bash

# 查看所有环境变量
go env

# 查看特定变量
go env GOPROXY
go env GOMODCACHE
go env GOPRIVATE

GOPROXY - 代理设置 #

bash

# 设置代理
go env -w GOPROXY=https://goproxy.cn,direct

# 多代理配置
go env -w GOPROXY=https://goproxy.cn,https://proxy.golang.org,direct

# 直接连接（不使用代理）
go env -w GOPROXY=direct

# 默认值
go env -w GOPROXY=https://proxy.golang.org,direct

GOPRIVATE - 私有模块 #

bash

# 设置私有模块（不走代理）
go env -w GOPRIVATE=github.com/mycompany/*,gitlab.company.com/*

# 同时设置 GONOSUMDB
go env -w GONOSUMDB=github.com/mycompany/*

GOMODCACHE - 缓存目录 #

bash

# 查看缓存位置
go env GOMODCACHE

# 设置缓存位置
go env -w GOMODCACHE=/path/to/cache

# 清理缓存
go clean -modcache

实战练习 #

练习一：创建 Web 服务 #

bash

# 1. 创建项目
mkdir webserver && cd webserver
go mod init webserver

# 2. 创建 main.go
cat > main.go << 'EOF'
package main

import (
    "github.com/gin-gonic/gin"
    "net/http"
)

func main() {
    r := gin.Default()
    
    r.GET("/hello", func(c *gin.Context) {
        c.JSON(http.StatusOK, gin.H{
            "message": "Hello, World!",
        })
    })
    
    r.Run(":8080")
}
EOF

# 3. 下载依赖
go mod tidy

# 4. 运行
go run main.go

练习二：使用第三方库 #

bash

# 1. 创建项目
mkdir cli-tool && cd cli-tool
go mod init cli-tool

# 2. 安装 cobra
go get github.com/spf13/cobra@latest

# 3. 创建 CLI 应用
cat > main.go << 'EOF'
package main

import (
    "fmt"
    "github.com/spf13/cobra"
)

func main() {
    var rootCmd = &cobra.Command{
        Use:   "cli-tool",
        Short: "A simple CLI tool",
        Run: func(cmd *cobra.Command, args []string) {
            fmt.Println("Hello from CLI!")
        },
    }
    
    rootCmd.Execute()
}
EOF

# 4. 运行
go run main.go

练习三：多包项目 #

bash

# 1. 创建项目结构
mkdir -p multipackage/{cmd/server,pkg/mathutil,internal/config}

# 2. 初始化模块
cd multipackage
go mod init multipackage

# 3. 创建包文件
cat > pkg/mathutil/calc.go << 'EOF'
package mathutil

func Add(a, b int) int {
    return a + b
}
EOF

cat > internal/config/config.go << 'EOF'
package config

type Config struct {
    Port int
}

func Default() *Config {
    return &Config{Port: 8080}
}
EOF

cat > cmd/server/main.go << 'EOF'
package main

import (
    "fmt"
    "multipackage/pkg/mathutil"
    "multipackage/internal/config"
)

func main() {
    cfg := config.Default()
    result := mathutil.Add(1, 2)
    fmt.Printf("Server on port %d, result: %d\n", cfg.Port, result)
}
EOF

# 4. 运行
go run cmd/server/main.go

常见问题 #

Q: go: module xxx: no matching versions for query #

bash

# 检查网络连接
# 配置代理
go env -w GOPROXY=https://goproxy.cn,direct

# 检查模块名称是否正确
go get github.com/correct/module@latest

Q: go: cannot find module providing package #

bash

# 运行 tidy 整理依赖
go mod tidy

# 检查 import 路径是否正确

Q: version “latest” invalid #

bash

# 使用 @latest 而不是 latest
go get package@latest

# 或指定具体版本
go get package@v1.0.0

下一步 #

掌握了基础使用后，继续学习：

依赖管理详解 - 深入了解依赖管理
版本管理指南 - 理解版本控制
常用命令速查 - 掌握更多命令