go 要求可执行程序必须位于 package main 中，而自定义包需独立定义、无 main 函数，并通过 import 在主程序中调用——本文详解目录结构、包声明、导入路径与运行流程。
go 要求可执行程序必须位于 package main 中，而自定义包需独立定义、无 main 函数，并通过 import 在主程序中调用——本文详解目录结构、包声明、导入路径与运行流程。
在 Go 中，“无法运行非 main 包”（go run: cannot run non-main package）是一个初学者高频错误，其根本原因在于 Go 的构建模型：go run 仅支持直接运行包含 func main() 的 package main 文件，而非任意包。自定义包（如 github.com/mypkg）本身不可执行，它必须被其他 main 程序导入并调用。
✅ 正确的项目结构与步骤
假设你的工作区路径为 /xyz/gocode，且已设置环境变量：
export GOPATH=/xyz/gocode
请严格遵循以下目录层级（Go 1.11+ 推荐使用模块模式，但此处兼容传统 GOPATH 工作流）：
/xyz/gocode/ ├── src/ │ └── github.com/ │ └── mypkg/ │ └── test.go # 自定义包源文件 └── main.go # 独立的入口程序
1. 定义自定义包（test.go）
// /xyz/gocode/src/github.com/mypkg/test.go
package mypkg
import "fmt"
// Hello 是导出函数（首字母大写），可供外部调用
func Hello() {
fmt.Println("Hello from mypkg!")
}
// Add 是另一个示例导出函数
func Add(a, b int) int {
return a + b
}⚠️ 注意：
- 包名（package mypkg）应与所在目录名一致；
- 导出标识符（函数、变量、类型）必须首字母大写（如 Hello，而非 hello）；
- 该文件中不能包含 func main()，否则将违反包设计原则。
2. 创建主程序（main.go）
// /xyz/gocode/main.go
package main
import (
"fmt"
"github.com/mypkg" // 导入路径 = $GOPATH/src/ 后的相对路径
)
func main() {
mypkg.Hello()
result := mypkg.Add(3, 5)
fmt.Printf("3 + 5 = %d\n", result)
}✅ 关键点：
- 主程序必须是 package main，且含 func main()；
- 导入路径 "github.com/mypkg" 对应 $GOPATH/src/github.com/mypkg；
- 不要将 main.go 放在 src/ 下——它属于可执行程序，通常置于 $GOPATH 根目录或独立项目根目录。
3. 运行程序
cd /xyz/gocode go run main.go
输出：
Hello from mypkg! 3 + 5 = 8
⚠️ 常见误区与解决方案
| 错误现象 | 原因 | 修复方式 |
|---|---|---|
| go run: cannot run non-main package | 直接对 test.go 执行 go run | 只对 main.go（或含 package main 的文件）运行 go run |
| cannot find package "github.com/mypkg" | GOPATH 未正确设置，或目录结构不匹配 | 检查 echo $GOPATH，确认 src/github.com/mypkg/test.go 路径存在 |
| undefined: mypkg.Hello | 函数名小写（如 hello()）未导出 | 将函数/变量名首字母大写，确保可导出 |
| import cycle not allowed | 主程序与自定义包相互 import | 包之间应为单向依赖，禁止循环引用 |
? 进阶建议：迁移到 Go Modules（推荐）
现代 Go（1.11+）已默认启用 Go Modules，无需依赖 GOPATH。你可在任意目录初始化模块：
mkdir myproject && cd myproject go mod init example.com/myproject
然后创建：
- mypkg/mypkg.go（包文件）
- main.go（导入 "example.com/myproject/mypkg"）
执行 go run main.go 即可，模块会自动解析本地包路径。
✅ 总结
自定义包不是“不能创建”，而是不能直接运行。它的角色是提供可复用的功能单元，必须由 package main 显式导入并驱动。牢记三要素：
? 结构合规：包代码置于 $GOPATH/src/{import-path}；
? 命名规范：包名 = 目录名，导出标识符首字母大写；
? 职责分离：自定义包不含 main，主程序负责组装与执行。
掌握这一范式，你就能稳健构建模块化 Go 应用——包括集成 cgo 调用 C 代码等进阶场景。
