💻 在 Windows 系統上配置 go-zero 開發環境教程

本教程將詳細介紹如何在 Windows 系統上配置 go-zero 微服務框架的開發環境，包括依賴安裝、路徑配置、常見問題等。

---

🧱 一、前置環境安裝

1. 安裝 Go

• 下載地址：https://go.dev/dl/
• 安裝時可自定義路徑（如：D:\Go）
• 安裝完成后，驗證是否成功：

go version

輸出示例：

go version go1.21.3 windows/amd64

? 建議使用 Go 1.18 及以上版本

---

2. 安裝 Git

• 下載地址：https://git-scm.com/downloads
• 安裝位置可自定義
• 安裝后驗證：

git --version

---

3. 安裝 Protocol Buffers（protoc）

go-zero 使用 Protobuf 定義 RPC 服務，需安裝 protoc 編譯器：

推薦方式：下載預編譯版本

• 下載地址：https://github.com/protocolbuffers/protobuf/releases
• 選擇適合的版本，如：protoc-21.12-win64.zip
• 解壓后，將 bin 目錄加入系統環境變量 PATH

驗證安裝：

protoc --version

---

?? 二、配置開發環境（遷移到 D 盤，避免占用 C 盤）

默認情況下，Go 會將依賴和工具安裝到 C:\Users\<用戶名>\go。我們建議將其遷移到 D 盤，提升可維護性和節省空間。

---

1. 配置環境變量（系統設置）

建議將 Go 安裝到 D 盤，并設置如下變量：

變量名	示例路徑
GOROOT	D:\Go
GOPATH	D:\GoWorkspace
GOBIN	D:\GoWorkspace\bin

然后將以下路徑加入系統環境變量 PATH：

D:\Go\bin
D:\GoWorkspace\bin

---

2. 手動創建工作目錄結構

在 D 盤創建以下目錄（如不存在）：

D:\GoWorkspace\src
D:\GoWorkspace\bin
D:\GoWorkspace\pkg

---

3. 配置 Go 環境參數

在終端中執行以下命令：

go env -w GOROOT=D:\Go
go env -w GOPATH=D:\GoWorkspace
go env -w GOBIN=D:\GoWorkspace\bin
go env -w GOPROXY=https://goproxy.cn,direct

查看當前配置：

go env

輸出示例：

GOROOT="D:\Go"
GOPATH="D:\GoWorkspace"
GOBIN="D:\GoWorkspace\bin"

---

📦 三、安裝 go-zero 與 goctl 工具

1. 初始化項目并自動拉取 go-zero

go mod init your_project
go get github.com/zeromicro/go-zero

---

2. 安裝 goctl（go-zero 的代碼生成工具）

推薦使用 go install 方式（Go 1.17+ 必須指定版本）：

go install github.com/zeromicro/go-zero/tools/goctl@latest

確保 $GOBIN（如：D:\GoWorkspace\bin）已加入環境變量 PATH，然后驗證安裝：

goctl --version

---

🚀 四、快速創建 go-zero 項目

創建 REST 項目

goctl api new demo
cd demo
go mod tidy
go run demo.go

生成結構：

.
├── demo.api
├── etc
│   └── demo.yaml
├── internal
│   ├── config
│   ├── handler
│   ├── logic
│   ├── svc
│   └── types
└── demo.go

---

創建 RPC 項目

goctl rpc new greet
cd greet
go mod tidy

---

🧩 五、常見問題排查

問題	解決方案說明
goctl 命令找不到	檢查 $GOBIN 是否已加入系統環境變量 PATH
protoc 報錯或未識別	檢查是否正確安裝并將 protoc.exe 所在的 bin 路徑加入了 PATH 環境變量
中文或空格路徑導致構建失敗	避免在項目路徑中使用中文、空格或特殊字符
推薦 IDE	推薦使用 GoLand 或 VSCode + Go 插件

---

🛠 六、附加技巧與推薦配置

1. goctl 插件模板升級與環境檢查

goctl upgrade -u
goctl env check

---

2. 使用 goctl 生成 handler 和 logic

goctl api go -api demo.api -dir .

會自動生成路由、業務邏輯和服務定義，極大提升開發效率。

---

? 項目目錄建議

推薦將項目統一放在：

D:\GoWorkspace\src\

或者使用 Go Modules，可將項目放在任意路徑下（如 D:\Projects\xxx），示例：

mkdir D:\Projects\demo
cd D:\Projects\demo
go mod init demo

---