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）比页面提示更准。- 用
