必须通过 frankenphp build 的 --ldflags 注入时间和版本号，因 FrankenPHP 二进制为静态可执行文件，PHP 层无 Git 环境、无 .git 目录、无法可靠读取外部文件或执行 shell 命令，且构建元信息仅在 Go 编译时可信；PHP 运行时无法感知构建上下文，唯有 -ldflags 能将字符串安全写入 Go 符号表供桥接调用。
构建时注入时间和版本号，必须通过 frankenphp build 的 --ldflags 传给 Go 编译器，不能靠环境变量或 PHP 层面的 date() 或 file_get_contents()。
为什么不能在 PHP 里动态读取时间或版本文件
打包后的 FrankenPHP 二进制是静态可执行文件，所有 PHP 逻辑（包括 index.php、worker.php）都运行在内置 PHP 运行时中，但构建元信息（如 Git commit、编译时间）不属于运行时上下文。常见错误是试图在 worker.php 里用 shell_exec('git log -1 --format=%h') 或读取 .version 文件——这些在离线部署或容器镜像中大概率失败，且破坏常驻内存模型的一致性。
- Git 命令依赖工作目录和 .git 文件夹，打包后通常不存在
- 读取外部文件会引入 I/O 不确定性，worker 模式下可能被缓存或并发竞争
- PHP 层无法感知构建时状态，而 Go 主进程才是唯一可信的构建入口点
正确做法：用 -ldflags 注入到 Go 变量
FrankenPHP 的构建流程基于 Go 的 go build，它支持通过 -ldflags 将字符串写入已声明的 var。你需要在 Go 扩展或自定义主程序中预留接收字段，例如：
package main
import "fmt"
var (
BuildTime string
BuildVersion string
GitCommit string
)
func GetBuildInfo() map[string]string {
return map[string]string{
"time": BuildTime,
"version": BuildVersion,
"commit": GitCommit,
}
}
然后在构建命令中注入：
立即学习“PHP免费学习笔记（深入）”；
frankenphp build \
--ldflags="-X 'main.BuildTime=$(date -u +%Y-%m-%dT%H:%M:%SZ)' \
-X 'main.BuildVersion=v1.2.3' \
-X 'main.GitCommit=$(git rev-parse --short HEAD)'" \
-o myapp
-
-X必须匹配包名.变量名，默认主包是main - 时间格式建议用 ISO 8601 UTC（
%Y-%m-%dT%H:%M:%SZ），避免时区歧义 -
$(git rev-parse --short HEAD)在 CI/CD 中要确保工作区干净且有 git history
如何在 PHP 代码里拿到这些值
Go 变量不能直接被 PHP 访问，需通过 FrankenPHP 提供的扩展机制桥接。最简方式是注册一个原生 PHP 函数：
// 在 Go 扩展中
func init() {
frankenphp.RegisterExtension(&php.Extension{
Name: "buildinfo",
Functions: []php.Function{
{
Name: "frankenphp_build_info",
Handler: func(r *php.Request) ([]interface{}, error) {
return []interface{}{GetBuildInfo()}, nil
},
},
},
})
}
PHP 中即可调用：
<?php $info = frankenphp_build_info(); echo $info['time']; // 输出构建时的 UTC 时间戳 ?>
- 不要尝试用
getenv()或$_SERVER读取构建信息——它们是运行时环境，不是构建时元数据 - 如果不用自定义扩展，也可在启动时把
BuildInfo写入$_SERVER['FRANKENPHP_BUILD_INFO']，但需修改 FrankenPHP 启动逻辑，侵入性强
CI/CD 中容易漏掉的关键点
本地测试能跑通，CI 构建却拿不到 Git 信息或时间不准，往往因为：
- Git clone 深度为 1（
--depth=1），导致git rev-parse失败；应加--no-single-branch --shallow-since='2 weeks ago'或直接禁用 shallow clone - CI runner 使用非 UTC 时区，
date命令输出带偏移；统一用date -u - 多阶段 Docker 构建中，
build阶段没挂载.git，或用了scratch基础镜像导致date命令不存在；改用alpine:latest并apk add coreutils
真正可靠的构建信息，只存在于 Go 编译那一刻的 -ldflags 字符串里——其他任何运行时补救都是妥协。
