Google App Engine Go 应用中相对导入路径报错的解决方案

Google App Engine（标准环境）要求所有 Go 包导入必须使用绝对路径（即以应用根目录为基准的完整包路径），不支持 ../ 等相对导入，否则会触发 parser: bad import 错误。

先说说这个问题的本质。在 Google App Engine 的 Go 运行时环境中，构建工具（go-app-builder）采用了一套相当严格的包解析策略。它会将应用根目录——也就是包含 app.yaml 的那个目录——视为 Go 工作区的 $GOROOT 或模块根。这意味着，所有 import 语句必须是从项目根开始的绝对包路径，而不是基于文件系统位置的相对路径。

举个例子，假设你的项目结构是这样的：

├── app.yaml
├── controllers/
│   ├── home/
│   │   └── home.go      // 想在此文件中导入 common 包
│   └── common/
│       └── common.go

如果在 controllers/home/home.go 中错误地写成：

import "../common"  // ❌ 错误：相对路径不被 App Engine 构建器接受

那么你就会遇到那个典型的报错信息：

go-app-builder: Failed parsing input: parser: bad import "../common" in controllers/home/home.go

正确的做法其实很简单：省略 ../，直接以项目根为起点书写包路径：

package home

import (
    "controllers/common"  // ✅ 正确：绝对包路径，等价于从项目根导入 ./controllers/common
)

func HomeHandler(w http.ResponseWriter, r *http.Request) {
    // 可正常使用 common 包中的类型或函数
    _ = common.DBConfig{}
}

这里有几个关键点需要特别注意：

• 不要添加前导 ./ 或 ../，也不要用完整的文件系统路径；
• 包名（如 common）必须与对应目录下的 package common 声明保持一致；
• 所有子包（如 controllers/auth、controllers/forum）均需遵循相同规则，统一使用 "controllers/xxx" 形式导入；
• 如果使用较新版本的 Go（1.11+）及 Go Modules，App Engine 标准环境仍然不兼容 go.mod（除非明确部署为 Go 1.16+ 的第二代运行时）。因此，请确保项目未启用模块模式，或者改用 App Engine flexible environment 或 Cloud Run，以获得现代 Go 工具链的支持。

说到底，App Engine 的这种构建约束，本质上是其沙箱化编译模型决定的——它需要可预测、无歧义的包依赖图。坚持使用从项目根出发的扁平化绝对导入路径，就能彻底规避这类解析失败的问题。