怎么让 Composer 能装到你的包
必须先有公开可访问的 Git 仓库（GitHub、GitLab 或其他），且主分支（通常是 main 或 master）里包含合法的 composer.json。Packagist 不收 zip 包，也不接受私有仓库直连——它只抓 Git 元数据。
常见错误现象：Package not found 或提交后 Packagist 页面显示 “This package is not auto-updated”，本质是没打通 Webhook 或仓库地址写错。
- 确保
composer.json里"name"格式为"vendor/name"（如"myorg/my-package"），且vendor和你在 Packagist 的用户名完全一致 - 仓库描述（
description）、类型（type，比如library）、自动加载配置（autoload）这三项不填或填错，会导致 Packagist 拒绝索引或用户安装后类找不到 - 别用中文路径、空格或大写字母命名 tag，
v1.0.0可以，V1.0或1.0版本会触发解析失败
怎么把 GitHub 仓库和 Packagist 绑定
不是“上传”，是“关联+触发同步”。Packagist 本身不存代码，只存元信息并定时或通过 webhook 拉取最新 tag。
使用场景：你 push 了一个新 tag（如 v2.1.0），想让 composer require myorg/my-package 立刻可用。
- 登录 Packagist，点右上角「Submit」→ 粘贴你的 GitHub 仓库 URL（必须是完整 HTTPS 地址，如
https://github.com/myorg/my-package） - 首次提交后，立刻去 GitHub 仓库 Settings → Webhooks → Add webhook，Payload URL 填 Packagist 提供的回调地址（格式类似
https://packagist.org/api/github?username=myorg），Content type 选application/json，只勾选Releases事件 - 如果已提交但没更新，手动在 Packagist 包页点「Update」按钮——但这只是临时补救，长期靠 webhook 自动触发
composer.json 哪些字段会影响安装体验
用户执行 composer require 时，实际依赖的是你声明的约束和自动加载规则。填错一个字段，可能让包装得上但跑不起来。
性能影响：autoload 配置不合理会导致 PSR-4 映射过深、文件扫描变慢；require 列了太多 dev-only 依赖会让生产环境也下无用包。
-
"autoload": { "psr-4": { "MyOrg\MyPackage\": "src/" } }—— 注意结尾斜杠和命名空间末尾反斜杠必须匹配，"MyOrg\MyPackage"和"MyOrgMyPackage"是不同写法，后者会报错 -
"require"里别写"php": "^8.0"这种宽泛约束，除非真测过所有子版本；更稳妥的是"php": ">=8.0.0 ，避免用户升级 PHP 后意外 break - 加
"minimum-stability": "stable"和"prefer-stable": true是给自己的包用的，对使用者无影响；真正影响用户的是你发的 tag 是否带-beta后缀
为什么 composer require 找不到刚发布的包
90% 是缓存或延迟问题，不是配置失败。Packagist 从接收 webhook 到可被 composer 命令查到，通常有 10–60 秒延迟；若超 5 分钟还找不到，才要排查。
容易踩的坑：composer clear-cache 没用，因为本地缓存不影响 Packagist 索引状态；composer search 默认只查已索引包，新包不会出现在结果里。
- 先直接访问
https://packagist.org/packages/vendor/name，看页面是否 200 且显示最新 tag —— 这是唯一可信判断依据 - 确认你用的不是私有 Packagist 镜像（比如公司内网源），有些镜像同步周期长达数小时甚至手动触发
- 如果页面显示正常但
composer require报Could not find package，试试加-vvv参数，看 Composer 实际请求的是哪个源，排除配置了repositories覆盖默认行为
事情说清了就结束
