# 安装、依赖与编译运行教程（Windows + VS Code）

## 1. 需要安装什么

| 组件 | 是否必需 | 作用 |
| --- | --- | --- |
| Go SDK | 必需 | 提供编译器、标准库、`go` 命令和测试工具 |
| VS Code | 推荐 | 编辑代码 |
| VS Code Go 扩展（`golang.Go`） | 推荐 | 代码补全、格式化、测试入口和调试支持 |
| Git | 克隆和提交仓库时必需 | 管理代码版本 |
| gopls | 编辑器功能推荐 | Go 语言服务，供扩展提供补全、跳转等功能 |
| Delve（`dlv`） | 断点调试时需要 | Go 调试器 |

Go 是编译型语言，安装 Go SDK 即可编译运行，不需要另外安装解释器。编辑器扩展不能代替 SDK。

本项目当前的 `go.mod` 声明 `go 1.27.3`，建议安装 Go 1.27.3 或更新稳定版本。这是当前学习环境使用的版本，不表示示例语法只能在该版本使用。

## 2. 安装 Go SDK

1. 前往 <https://go.dev/dl/> 下载适合 Windows 系统架构的安装包。
2. 常见 Intel / AMD 64 位电脑选择 `windows-amd64.msi`；ARM64 设备选择对应架构。
3. 按向导安装，记录安装位置。
4. 彻底退出并重新打开 VS Code、PowerShell。已运行的程序可能还保留旧 PATH。
5. 在新的终端检查：

```powershell
go version
go env GOROOT GOPATH
```

如果提示找不到 `go`：

- 检查 SDK 安装目录下是否存在 `bin\go.exe`。
- 将这个 `bin` 目录加入 Windows 的 `Path` 环境变量，然后重新打开终端。
- 本次机器上检测到的位置是 `D:\Work_software\Go_sdk\bin`；其他机器请使用实际安装路径，不要直接照搬。
- 可先用完整路径验证（路径含空格时也使用 `&`）：

```powershell
& 'D:\Work_software\Go_sdk\bin\go.exe' version
```

通常无需手动配置 `GOROOT` 或 `GOPATH`。`GOROOT` 是 SDK 目录，`GOPATH` 默认用于工具安装、模块缓存等用途，不要求把本项目放进 `GOPATH`。

## 3. 安装 VS Code 和 Go 扩展工具

1. 从 <https://code.visualstudio.com/> 安装 VS Code。
2. 扩展面板（`Ctrl + Shift + X`）搜索 `golang.Go`，安装由 Go Team at Google 发布的 Go 扩展。
3. 使用“打开文件夹”打开本项目根目录。
4. 打开 `lessons/01_hello/main.go`，根据提示安装所需工具；或按 `Ctrl + Shift + P`，执行 `Go: Install/Update Tools`。
5. 安装 `gopls`；需要 F5 断点调试时再安装 `dlv`。

也可手动安装这些**开发工具**（需要网络，不属于项目运行依赖）：

```powershell
go install golang.org/x/tools/gopls@latest
go install github.com/go-delve/delve/cmd/dlv@latest
```

工具通常安装在 `GOPATH\bin`，设置了 `GOBIN` 时以 `GOBIN` 为准。可执行 `go env GOPATH GOBIN` 查看。希望在终端直接执行 `gopls` / `dlv` 时，把工具安装目录加入 PATH。

`@latest` 会随上游更新变化，并可能要求更新的 Go 版本。优先使用扩展推荐版本；若有版本兼容报错，按工具官方说明升级 SDK 或安装兼容的工具版本。

## 4. 获取项目与处理依赖

### 已经打开当前项目

直接在项目根目录打开终端即可。仓库已有公共 `go.mod`，所有例程共用它，**不要在根目录或例程目录重复执行 `go mod init`**。

每个例程独占 `lessons/编号_主题/` 目录，拥有自己的程序、测试和说明。根目录只放公共配置及教程，不放程序入口。

### 在新电脑克隆

先从 <https://git-scm.com/downloads/win> 安装 Git，重启终端后执行：

```powershell
git --version
git clone http://vk-fly.com:10880/ZhuTianShuai/go_learn.git
Set-Location go_learn
```

如果远程要求认证，请通过本机 Git 凭据管理器或服务端支持的安全方式登录，不要把密码写进远程 URL、代码或文档。该地址使用明文 HTTP，建议服务端启用 HTTPS 或改用 SSH。

### 本项目的依赖

当前只使用标准库 `fmt` 和 `testing`，它们随 SDK 提供，**无需 `go get` 或其他第三方包安装命令**。

可以在项目根目录执行：

```powershell
go mod tidy
```

该命令根据源码整理依赖。当前没有第三方模块时，没有 `go.sum` 是正常现象。未来增加外部依赖后，可以用 `go mod download` 下载已声明的模块依赖。

未来确实需要添加某个第三方库时，再执行 `go get 模块路径@版本`，并检查、提交依赖声明的变更。`go install ...@版本` 用于安装命令行工具，不等于为项目添加库依赖。

若依赖下载失败，先检查网络和代理配置：

```powershell
go env GOPROXY
```

根据所在网络与组织要求选用可信代理，不要通过关闭校验或使用不可信镜像来绕过问题。本示例运行不需要下载第三方库；如果本地 Go 版本低于模块要求，Go 的自动工具链选择机制仍可能触发工具链下载，因此推荐先安装匹配的 SDK。

## 5. 运行第一个程序

在项目根目录指定第 01 课的目录：

```powershell
go run ./lessons/01_hello
```

预期输出：

```text
你好，Go！
欢迎开始 Go 语言学习与测试。
2 + 3 = 5
```

修改代码并保存后，再次运行该命令即可。也可以从项目根目录进入本课：

```powershell
Set-Location lessons/01_hello
go run .
```

这里的 `.` 表示当前例程所在的包，能包含本课目录中的多个源码文件。根目录没有 Go 程序入口，不要在根目录执行 `go run .`。每次只运行一课，不使用 `go run ./...` 同时启动所有例程。

下文公共命令按项目根目录执行；如果刚进入本课，可用 `Set-Location ../..` 返回根目录。

## 6. 格式化、测试与检查

```powershell
# 格式化所有包
go fmt ./...

# 只测试第 01 课
go test -v ./lessons/01_hello

# 测试所有课程
go test -v ./...

# 查看测试覆盖率
go test -cover ./...

# 静态检查常见问题
go vet ./...
```

`lessons/01_hello/main_test.go` 验证了正数、零、负数和正负混合相加。`_test.go` 文件不会被编译进正常程序。覆盖率可能不到 100%，因为当前只为加法函数写了测试，没有对终端输出入口做测试。

## 7. 编译为 Windows 可执行文件

在项目根目录的 PowerShell 执行，每课使用单独的产物目录：

```powershell
# 创建第 01 课的构建输出目录，重复执行也可以
New-Item -ItemType Directory -Force bin/01_hello | Out-Null

# 只编译第 01 课
go build -o ./bin/01_hello/hello.exe ./lessons/01_hello

# 启动编译后的程序
.\bin\01_hello\hello.exe
```

命令解释：

- `go build` 是编译命令。
- `-o ./bin/01_hello/hello.exe` 指定输出文件的路径和名称。
- `./lessons/01_hello` 指定要编译的例程目录。
- `go run ./lessons/01_hello` 则是先编译再立即运行，不会在指定输出目录保留可执行文件，并不是解释执行。
- 修改源码后，需要重新执行编译命令；已经生成的可执行文件不会自动变化。

Go 与 C 类似，也有主函数入口：可执行程序使用 `package main`，并声明无参数、无返回值的 `func main()`。它不需要 C 中的 `return 0`，源码也不一定必须叫 `main.go`。详细示例和 C / Go 对照见 [第 01 课：主函数入口](./lessons/01_hello/README.md#go-也有-main-主函数吗)。

编译成功时通常没有额外输出。PowerShell 运行当前目录下的程序需要 `./` 或 `.\` 前缀，不能只输入 `hello.exe`。

编译后的程序可以在兼容的 Windows 和 CPU 架构环境运行，一般不需要目标电脑安装 Go SDK。本项目没有 C 语言依赖。`bin` 已加入 Git 忽略规则，不提交可执行文件。

## 8. 在 VS Code 中调试

1. 打开 `lessons/01_hello/main.go`，在函数内的可执行语句左侧点击，添加断点。
2. 按 F5，如提示安装 Delve 则按提示安装。
3. 如需选择调试配置，选择 Go 的当前包（Launch Package）模式，目标应是当前文件所在的例程目录（`${fileDirname}`），不是仓库根目录。
4. 用 F10 单步执行，观察变量 `a`、`b` 的值。

优先先确认在根目录运行 `go run ./lessons/01_hello` 能正常执行，再排查编辑器调试问题。不需要额外安装 Code Runner 扩展。

## 9. 日常 Git 提交流程

在仓库初始化和首次推送完成后，日常修改可使用：

```powershell
git status
git diff
git add -A -- README.md INSTALL.md lessons go.mod .gitignore
git commit -m "docs: update Go learning notes"
git push
```

如果提示缺少提交身份，请设置你自己的用户名与邮箱，可只对当前仓库设置：

```powershell
git config user.name "你的名字"
git config user.email "你的邮箱"
```

提交前检查暂存内容，确保没有密码、令牌、私钥或其他敏感文件。不要为了覆盖远程历史而随意使用强制推送。