composer.json 的 version 字段不应手动维护，因其仅作元信息展示，实际版本由 Git tag 决定；手动修改会导致 composer show 输出与真实版本不一致，干扰调试和依赖解析。

为什么 composer.json 的 version 字段不该手动维护

它根本不会被 Composer 读取——这个字段仅作元信息展示，实际版本判定完全依赖 VCS（如 Git）的 tag。手动改 version 不但无效，还会造成 composer show your/package 输出与真实安装版本不一致，干扰调试和依赖解析。

• Composer 安装时只看 Git tag（例如 v2.1.0），tag 名必须符合语义化版本格式（vX.Y.Z 或 X.Y.Z）
• 发布前无需修改 composer.json；CI 流程中应由脚本生成 tag 并推送到远程
• 若你用 composer require your/package:dev-main 测试开发版，也无需 tag，但正式发布必须打 tag

GitHub Actions 中自动打 tag 并触发 Packagist 同步

Packagist 不再支持密码登录，必须使用 API token + Webhook 或 GitHub Action 主动推送。推荐后者：用 packagist.org 提供的 packagist/packagist-action，它会在 push tag 后立即同步，避免手动点击 “Update”。

• 确保你的包已在 packagist.org 手动提交一次（填入 GitHub 仓库 URL 即可）
• 在 Packagist 账户设置中生成一个 API Token，添加为 GitHub repo 的 secret：PACKAGIST_API_TOKEN
• CI 脚本只需在成功创建 tag 后调用该 action，无需额外配置 webhook

name: Release
on:
  workflow_dispatch:
    inputs:
      version:
        description: 'Semantic version (e.g. v1.2.0)'
        required: true
jobs:
release:
runs-on: ubuntu-latest
steps:
uses: actions/checkout@v4
with:
fetch-depth: 0
name: Create tag and push
run: |
git config user.name 'github-actions'
git config user.email 'github-actions@github.com'
git tag ${{ github.event.inputs.version }}
git push origin ${{ github.event.inputs.version }}
name: Notify Packagist
uses: packagist/packagist-action@v1
with:
api-token: ${{ secrets.PACKAGIST_API_TOKEN }}
package-name: your-vendor/your-package

如何防止重复发布或跳过预发布版本校验

直接 push tag 可能误发非语义化 tag（如 v1.2、release-3），导致 Packagist 同步失败或版本混乱。应在 CI 中加入 tag 格式校验和已存在性检查。

• 用 git ls-remote --tags origin 检查 tag 是否已存在，避免重复推送
• 用正则 ^v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ 验证输入是否为合法 semver
• 若需支持 alpha/beta 版本，Packagist 默认识别 v1.0.0-alpha 为 unstable，无需额外配置 minimum-stability

本地测试发布流程前必须验证的三件事

别等 CI 报错才回头改——本地就能跑通核心链路。

• 执行 git tag -a v1.0.0 -m "Release v1.0.0" + git push origin v1.0.0，确认 Packagist 页面几秒内更新了 latest version
• 在另一个项目中运行 composer require your-vendor/your-package:^1.0，验证能否正确拉取并加载 autoload
• 检查 composer.json 的 autoload 字段路径是否与实际目录结构一致——常见错误是 "psr-4": {"Your\\Package\\": "src/"} 写成 "src/Your/Package/"

Packagist 同步延迟极低，但 tag 推送后若未立刻生效，优先检查是否漏了 API token 权限或包名拼写错误；CI 日志里 packagist-action 的响应体（含 status 和 message）比页面提示更准。