必须先完成go环境配置、模块初始化和gin框架下载，才能成功运行gin web服务：验证go version≥1.25、设置goproxy、执行go mod init、go get gin、编写main.go并go run启动服务。

要在本地机器上成功运行一个基于 Gin 的 Go Web 服务，必须先完成框架下载与项目依赖初始化——这一步缺失会导致 import "github.com/gin-gonic/gin" 报错、go run 失败或模块校验失败。

确认 Go 环境可用

打开终端，执行：
go version

输出应类似 go version go1.25.1 darwin/arm64 或更高版本。Gin 要求 Go ≥ 1.25，低于此版本会无法编译或触发 module 兼容错误。【若无输出或提示 command not found，请先安装 Go 并配置 PATH】

接着验证模块代理是否生效：
go env GOPROXY

推荐值应包含 https://goproxy.cn 或 https://proxy.golang.org。国内用户若未配置，go get 很可能卡在 github.com 域名解析或连接超时。

创建项目并初始化模块

新建项目目录并进入：
mkdir my-gin-app && cd my-gin-app

运行模块初始化命令：
go mod init my-gin-app

该命令生成 go.mod 文件，声明模块路径。文件名不必与 GitHub 仓库一致，但需是合法的 Go 包导入路径（不含空格、大写字母或下划线开头）。【跳过此步将导致 go get 无法写入依赖，后续所有 import 都会报错 unresolved import】

下载并引入 Gin 框架

方法一：直接获取最新稳定版
go get github.com/gin-gonic/gin

Gin框架 1.9.0

Gin框架 1.9.0版本源码包下载，版本号 1.9.0，适合需要 sonic JSON 支持、路由修复和内容协商改进的 Go Web 开发场景。

下载

方法二：指定 v1.12.0 版本（推荐用于生产环境锁定）
go get github.com/gin-gonic/gin@v1.12.0

执行后，go.mod 中自动添加一行：
require github.com/gin-gonic/gin v1.12.0

同时生成或更新 go.sum，记录每个依赖的加密哈希值。这一步不可跳过，否则 go run 时会报 missing go.sum 或 checksum mismatch。

编写并运行第一个 Gin 服务

创建 main.go 文件：
touch main.go

写入以下代码：

package main
import "github.com/gin-gonic/gin"

func main() {
  r := gin.Default()
  r.GET("/ping", func(c *gin.Context) {
    c.JSON(200, gin.H{"message": "pong"})
  })
  r.Run(":8080")
}

保存后执行：
go run main.go

终端输出应含 [GIN-debug] Listening and serving HTTP on :8080。此时打开浏览器访问 https://www.php.cn/link/4f9ec8df9f1f7b84f2a3f69c4af72ba9，返回 JSON {"message":"pong"} 即表示安装与运行全部成功。