Git标签应严格使用vX.Y.Z格式并签名，确保Composer识别；GitHub Actions需用ref前缀过滤PHP版本标签；Docker构建须通过CI提取主版本号传参，避免硬编码。
Git 标签怎么打 PHP 版本号
PHP 项目用 Git 管理时，版本号应严格遵循 MAJOR.MINOR.PATCH 格式（如 v8.1.23），并打带签名的轻量标签或附注标签。不推荐用分支名或 commit message 模糊标识版本，否则 CI/CD 和包管理器（如 Composer）无法可靠识别。
实操建议：
- 发布前先确保当前工作区干净，且
composer.json中的"version"字段已更新（如"version": "8.1.23"） - 执行
git tag -s v8.1.23 -m "Release PHP 8.1.23"（-s表示 GPG 签名，CI 流水线常校验此签名） - 推送标签需显式操作：
git push origin v8.1.23或批量推送：git push origin --tags - 避免用
git tag v8.1.23 -a（-a是附注标签但没指定消息，会弹出编辑器，易中断自动化）
Composer 如何读取 Git 标签作为版本
Composer 默认把 Git 标签解析为稳定版本，前提是标签名匹配语义化版本正则（^v?\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$）。若标签是 php-8.1.23 或 release-8.1.23，Composer 会忽略它，导致 composer require vendor/package:8.1.23 安装失败。
常见错误现象：
立即学习“PHP免费学习笔记（深入）”；
-
Could not find package vendor/package in a version matching "8.1.23"—— 实际标签存在，但格式不合规 -
Package vendor/package has a dependency on php ^8.1 but the locked version is 8.0.30—— 标签没触发 PHP 版本约束重检，因 Composer 没把它当正式 release
正确做法：
- 只用
vX.Y.Z或X.Y.Z（不带前缀）格式打标签 - 在
composer.json的"require"中明确写"php": "^8.1"，而非"php": ">=8.1.0"，前者能被 Composer 的版本解析器更好识别 - 打完标签后运行
composer validate，确认version字段与标签一致
GitHub Actions 自动检测 PHP 版本标签并构建
GitHub Actions 中不能仅靠 on: push: tags 触发构建，因为默认事件不区分是否为 PHP 版本标签 —— 可能误触发 v1.0.0（某个工具库）和 v8.2.0（PHP 本身）的构建逻辑。
使用场景：你维护一个 PHP 扩展，需在每次 PHP 官方发布新版本时自动编译兼容包。
关键配置点：
- 用
on: push: tags: ['v[0-9]+.[0-9]+.[0-9]+']过滤，但注意 GitHub Actions 的 glob 不支持正则，得改用if: startsWith(github.event.ref, 'refs/tags/v') && contains(github.event.ref, '.') && !contains(github.event.ref, '-') - 在 job 中提取版本号：
PHP_VERSION=${GITHUB_REF#refs/tags/v}，然后用setup-php动作加载对应版本：uses: shivammathur/setup-php@v2+with: php-version: ${{ env.PHP_VERSION }} - 别忘了检查
php -v输出是否真为预期版本 —— 某些旧版setup-php对v8.3.0RC3解析异常，会回退到8.3稳定版
Docker 构建中如何从 Git 标签推导 PHP 基础镜像
Dockerfile 本身不解析 Git 标签，必须靠构建参数或外部注入。直接写 FROM php:8.1-cli 是硬编码，会导致每次 PHP 升级都要手动改 Dockerfile。
性能与兼容性影响：
- 若用
ARG PHP_VERSION=8.1+FROM php:${PHP_VERSION}-cli，需确保PHP_VERSION在docker build --build-arg中传入，否则 fallback 到空字符串，构建失败 - 更健壮的做法：CI 脚本中用
git describe --tags --exact-match 2>/dev/null获取当前标签，再提取主版本号，例如v8.1.23→8.1，最后传给 Docker - 注意 Alpine 镜像命名差异：
php:8.1-cli-alpine存在，但php:8.1.23-cli-alpine通常不存在 —— 官方只维护X.Y级别 tag，不要试图用完整 PATCH 号拉取基础镜像
标签不是装饰，是 PHP 生态里版本传递的最小可信单元。漏掉签名、格式错一位、或没同步更新 composer.json，下游就可能拉到错误的依赖树。
