GitLab Runner 本身不依赖 PHP 或 phpenv，PHP 版本应在 job 的 before_script 中动态配置（如 phpenv local 8.2 或指定 php:8.2-cli 镜像），而非 Runner 全局设置；推荐使用 docker executor + 官方 PHP 镜像以确保环境隔离与可复现性。
GitLab Runner 本身不依赖 PHP 环境运行，phpenv 是给 PHP 项目用的版本管理工具，不是 Runner 的运行前提。你真正需要的，是在 Runner 执行作业（job）时，让 PHP 项目能用上指定版本的 PHP —— 这个动作发生在 script 阶段，而非 Runner 启动阶段。
为什么不能在 Runner 全局配置里用 phpenv 切换 PHP 版本
Runner 进程自身是 Go 编写的二进制，不解析 PHP，也不读取 phpenv 的环境变量。它只负责拉起 shell 或容器，然后执行 .gitlab-ci.yml 里定义的命令。你在注册 Runner 时选 shell executor，它就调用系统默认 shell；选 docker，就启动一个容器。无论哪种，PHP 版本都得在 job 运行时动态准备。
常见错误现象：php -v 显示系统默认 PHP（比如 8.1），但项目要求 8.2，结果 composer install 报错或扩展加载失败。
-
phpenv必须在每个 job 的before_script中初始化，不能靠 Runner 启动脚本“一劳永逸” - 如果你用
shellexecutor，需确保目标机器已安装phpenv及所需 PHP 版本，并且gitlab-runner用户有权限读写~/.phpenv - 用
dockerexecutor 更稳妥：直接指定带对应 PHP 版本的镜像，比如php:8.2-cli，完全绕过phpenv管理成本
在 .gitlab-ci.yml 中安全使用 phpenv（仅限 shell executor）
前提是你已手动在 Runner 服务器上为 gitlab-runner 用户装好 phpenv 和多个 PHP 版本（如 7.4、8.1、8.2）。否则 job 会卡在 phpenv install 步骤，且该步骤每次都会重装，极慢又不可靠。
立即学习“PHP免费学习笔记（深入）”；
推荐做法是把版本切换逻辑封装进 before_script，并加校验：
before_script: - export PATH="$HOME/.phpenv/bin:$PATH" - eval "$(phpenv init -)" - phpenv local 8.2 - php -v | grep "8.2" || (echo "PHP 8.2 not available" && exit 1)
- 必须用
phpenv local（非global），避免污染其他 job -
phpenv init -输出的是 shell 函数定义，要用eval加载，否则phpenv命令不可用 - 最后加
php -v校验，防止因路径错乱导致静默降级到系统 PHP
更推荐：用 docker executor + 官方 PHP 镜像替代 phpenv
绝大多数 PHP 项目 CI 场景下，phpenv 是冗余负担。Docker 镜像自带完整、隔离、可复现的 PHP 环境，还省去扩展编译和依赖冲突问题。
示例（适配 Laravel/ThinkPHP 等主流框架）：
test:
image: php:8.2-cli
before_script:
- apt-get update && apt-get install -y unzip git curl
- curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
script:
- composer install --no-interaction --optimize-autoloader
- vendor/bin/phpunit --no-coverage
- 镜像名直接体现 PHP 版本，语义清晰，CI 日志一眼可查
- 不同 job 可用不同
image，比如测试用php:8.2-apache，部署用php:8.2-cli，互不干扰 - 避免在 Runner 主机上维护多套 PHP，降低运维复杂度和安全风险
真正容易被忽略的点：即使你坚持用 phpenv，也别把它和 Runner 注册流程耦合。Runner 只管执行，PHP 版本是 job 的契约，不是基础设施的配置。把环境准备逻辑下沉到 .gitlab-ci.yml，才能保证 pipeline 在任意 runner 上行为一致。
