Go 語言概論 – Go 命令列工具（`go run`, `go build`, `go install`）

簡介

在學習 Go 語言的過程中，最常接觸到的就是 Go 的命令列工具。這些工具不只是編譯器，更是整個開發、測試、部署工作流程的核心。

go run 讓你可以 即時執行 程式碼，適合快速驗證想法或寫教學範例。
go build 產生 獨立的執行檔，是正式發佈或測試二進位檔時的主要手段。
go install 則把編譯好的套件或二進位檔 安裝到 $GOPATH/bin（或 $HOME/go/bin），方便在任何目錄下直接呼叫。

掌握這三個指令，你就能在本機、CI/CD 或容器環境中自如地管理 Go 程式的編譯與部署，提升開發效率與專案可維護性。

核心概念

1. `go run` – 直接執行 Go 程式

go run 會先把指定的 .go 檔案（或套件）編譯成暫存的執行檔，然後立即執行，執行完畢後會自動清除暫存檔。

// hello.go
package main

import "fmt"

func main() {
    fmt.Println("Hello, Go!")
}

$ go run hello.go
Hello, Go!

小技巧：若專案有多個檔案，只要把目錄傳給 go run，Go 會自動偵測同一個套件內的所有檔案。

$ go run ./cmd/myapp

為什麼使用 `go run`？

快速驗證：寫完小段程式碼即可看到結果，省去手動編譯的步驟。
教學示範：在課堂或部落格文章中直接展示程式執行結果。

2. `go build` – 產生可執行檔或套件檔案

go build 會把指定的套件編譯成 二進位執行檔（若是 main 套件）或 .a 靜態庫（若是非 main 套件），並將結果放在當前目錄或 -o 指定的路徑。

基本範例：編譯單一檔案

$ go build -o hello hello.go
$ ./hello
Hello, Go!

編譯整個專案（含子目錄）

假設專案結構如下：

myproj/
├─ cmd/
│  └─ server/
│     └─ main.go
├─ internal/
│  └─ db/
│     └─ db.go
└─ go.mod

$ cd myproj/cmd/server
$ go build -o server .
$ ./server
Server started on :8080

交叉編譯（Cross‑compile）

Go 原生支援跨平台編譯，只需要設定環境變數 GOOS 與 GOARCH。

# 產生 Windows 64 位元的執行檔
$ GOOS=windows GOARCH=amd64 go build -o app.exe .

注意：交叉編譯時若使用了 Cgo，必須確保目標平台的 C 編譯器可用。

3. `go install` – 安裝套件或二進位檔

go install 的行為類似 go build，但會把產出的檔案放到 GOPATH（或預設的 $HOME/go）的 bin 目錄，讓你可以在任何路徑下直接執行。

# 安裝一個 CLI 工具
$ go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
$ which golangci-lint
/home/username/go/bin/golangci-lint

安裝自訂工具

$ cd $HOME/go/src/github.com/yourname/hello-cli
$ go install .
$ hello-cli
Hello from my CLI!

go install 也支援 版本安裝（自 Go 1.17 起），直接在指令後加上 @vX.Y.Z 即可。

$ go install github.com/google/uuid@v1.3.0

程式碼範例彙總

範例	說明
`go run hello.go`	快速執行單一檔案
`go run ./cmd/...`	執行整個 `cmd` 目錄下的所有 main 套件
`go build -o myapp main.go`	編譯產生執行檔 `myapp`
`GOOS=linux GOARCH=amd64 go build -o app-linux .`	交叉編譯成 Linux 64 位元執行檔
`go install ./...`	安裝當前模組所有可執行套件至 `$HOME/go/bin`
`go install github.com/urfave/cli/v2/cmd/cli@latest`	安裝遠端套件的最新版本

常見陷阱與最佳實踐

陷阱	說明	解決方式 / 最佳實踐
忘記設定 `GO111MODULE=on`	在舊版 Go 中，若在 `$GOPATH` 外工作，module 可能不會被啟用。	使用 Go 1.16+ 時，module 預設開啟；若仍有問題，手動 `export GO111MODULE=on`。
交叉編譯時缺少 Cgo	使用 `cgo` 的套件在交叉編譯時會失敗。	若不需要 Cgo，加入 `CGO_ENABLED=0`；需要時安裝對應平台的交叉 C 編譯器。
`go install` 把舊版二進位覆蓋	同名工具在不同版本間安裝會互相覆蓋。	使用版本化的路徑或手動搬移二進位檔，例如 `go install example.com/tool/v2@v2.1.0`。
未使用 `-mod=readonly`	在 CI 環境中，`go build` 可能會自動下載缺少的模組，導致不可預期的變動。	在 CI pipeline 加上 `go build -mod=readonly`，確保只使用 `go.mod` 中鎖定的版本。
產出檔案放在錯誤目錄	`go build` 預設把執行檔放在當前目錄，容易混淆。	使用 `-o ./bin/app` 統一管理產出檔案，並加入 `.gitignore`。

最佳實踐

統一編譯腳本：在 Makefile 或 Taskfile.yml 中封裝 go build、go install、交叉編譯等指令，避免手動錯誤。
使用 -trimpath：在發佈二進位檔時加入 -trimpath，去除本機路徑資訊，提升可重現性。
CI/CD 中加入 go vet、go test：在編譯前先跑靜態分析與測試，確保二進位檔的品質。

實際應用場景

本機開發與快速迭代
- 使用 go run 直接執行程式，省去編譯步驟，適合開發 API 原型或演算法驗證。
自動化建置與發布
- 在 GitHub Actions、GitLab CI 中使用 go build -o ./dist/app -ldflags="-s -w" 產出最小化的二進位檔，搭配 Dockerfile COPY ./dist/app /app，完成容器化部署。
CLI 工具的分發
- 透過 go install 把自訂的命令列工具安裝到 $HOME/go/bin，使用者只要把該路徑加入 $PATH，即可在任何目錄下呼叫。
跨平台發佈
- 針對 Windows、macOS、Linux 各自交叉編譯，產出不同平台的安裝包（.exe、.tar.gz、.dmg），滿足多元使用者需求。
模組化開發
- 大型專案常把共用程式庫放在 internal/ 或 pkg/，使用 go build ./... 確保所有子模組都能成功編譯，避免因單一套件失效導致整體建置失敗。

總結

go run、go build、go install 是 Go 生態系中最基礎、也是最常用的三個命令列工具。
快速驗證 → go run；產出可執行檔 → go build；全域安裝 → go install。
熟悉交叉編譯、環境變數 (GOOS, GOARCH, CGO_ENABLED) 以及常見的陷阱，能讓你在本機、CI/CD、容器等多種環境中自如地管理 Go 程式。
結合 Makefile、CI pipeline 與 最佳實踐（如 -trimpath、-mod=readonly），即可打造可靠、可重現的建置流程，提升團隊開發效率與產品品質。

掌握這三個指令，你就能在 開發、測試、部署 的每一個階段都游刃有餘，讓 Go 成為你最得力的開發夥伴。祝你寫程式快快樂樂、編譯順順利利！

Go 語言概論 – Go 命令列工具（go run, go build, go install）

簡介