本文详解 go 项目中本地包导入失败的常见原因，重点说明 gopath 目录结构规范、import 路径与文件系统路径的映射关系，并提供可立即生效的配置方案与现代替代方案（go modules）。
在 Go 中，import "app/model" 报错（如提示 /usr/local/go/src/pkg/model (from $GOROOT)）本质上是 import 路径未被 Go 工具链识别为有效包路径。根本原因在于：Go 的 import 语句不解析相对路径或任意本地目录，而是严格依据 GOPATH（旧版）或模块根目录（Go 1.11+）来定位源码。
✅ 正确做法：遵循 Go 的包路径约定
方案一：基于 GOPATH（适用于 Go < 1.13 或禁用模块的场景）
确保你的项目位于 $GOPATH/src/ 下，并使用完整路径作为 import 路径：
# 假设 GOPATH=/home/user/go export GOPATH=/home/user/go # 正确的目录结构（注意：必须在 src/ 下） $GOPATH/src/app/model/file1.go $GOPATH/src/app/main.go
此时 main.go 中应这样导入：
package main
import (
"fmt"
"app/model" // ✅ 正确：import 路径 = $GOPATH/src/ 后的相对路径
)
func main() {
fmt.Println(model.SomeFunc()) // 假设 model 定义了导出函数
}⚠️ 注意事项：import "app/model" 成立的前提是该路径真实存在于 $GOPATH/src/app/model/；不要将代码放在 $GOROOT/src/（Go 安装目录），否则会误触发系统包查找；go build 必须在 $GOPATH/src/app/ 或其子目录下执行，或使用 go build app（从 GOPATH 根启动构建）。
方案二：推荐 —— 使用 Go Modules（Go 1.11+ 默认启用）
彻底摆脱 GOPATH 限制，支持任意目录结构：
# 在你的项目根目录（如 ~/myproject/app/）初始化模块 cd ~/myproject/app go mod init app # 此时目录结构可保持原样： # app/ # model/ # file1.go # file2.go # main.go
main.go 导入方式不变：
import "app/model" // ✅ 模块名即为 import 路径前缀
Go Modules 会将 go.mod 中定义的模块名（module app）作为根路径解析 import。构建时自动处理依赖，无需依赖 $GOPATH。
✅ 验证是否启用模块：运行 go env GO111MODULE，输出 on 即启用；若为 auto，在含 go.mod 的目录下自动激活。
? 常见错误排查
- ❌ 错误：cannot find package "app/model"
→ 检查 go.mod 是否存在且 module 声明正确；或确认 $GOPATH/src/app/model/ 是否存在且 file1.go 包声明为 package model（非 package main）。 - ❌ 错误：import "app/model" is a program, not an importable package
→ 确保 model/ 下所有 .go 文件首行是 package model（小写，且与目录名一致），而非 package main。
? 总结
| 场景 | 推荐方案 | import 写法 | 关键约束 |
|---|---|---|---|
| 新项目 / Go 1.13+ | Go Modules | import "app/model" | go mod init app + 目录内有 go.mod |
| 遗留项目 / 强制 GOPATH | 放入 $GOPATH/src/ | import "app/model" | 路径必须严格匹配 $GOPATH/src/app/model |
现代 Go 开发强烈建议统一使用 Go Modules —— 它解耦了代码位置与 import 路径，支持版本化依赖，且已成为 Go 生态标准。执行 go mod init <module-name> 是开启这一能力的第一步。
