初始化可发布PHP包需遵循PSR-4规范：创建src/目录，按命名空间（如MyPackage）组织文件；composer.json中必设"type": "library"和"autoload": {"psr-4": {"MyPackage": "src/"}}，vendor名须与Packagist账号一致。
怎么初始化一个可发布的 PHP 包目录结构
Composer 包不是随便扔个 index.php 就能发的，它得符合 PSR-4 自动加载规范，且有明确的命名空间和入口点。你本地目录结构没对，composer install 会装不上，别人 require 也会报 Class not found。
推荐最简但合规的起点：
-
src/目录放主代码，比如src/MyPackage/Helper.php - 命名空间必须和目录结构一致，例如
namespace MyPackage; -
composer.json里写清楚"autoload": { "psr-4": { "MyPackage\": "src/" } } - 包名格式为
vendor/name（如me/string-utils），vendor必须是你 Packagist 账号名，不能瞎填
为什么 composer.json 的 type 和 autoload 字段不能省
很多人跳过 type，结果包被 Packagist 当成普通项目忽略；不配 autoload，别人 require 后类根本加载不了——这不是报错问题，是静默失效。
关键配置项说明：
立即学习“PHP免费学习笔记（深入）”；
-
"type": "library"是必须的，否则 Packagist 不收录（project或空值都不行） -
"autoload"至少要含psr-4，测试用composer dump-autoload -o看是否生成了映射 -
"require"里别写"php": "^8.0"这种宽泛约束，除非你真测过所有 8.x 版本；更稳妥是"php": ">=8.0.0 - 加
"license": "MIT"，没许可证 Packagist 会警告，有些公司 CI 会直接拒用
发布前必须验证的三个终端命令
别急着 push 到 GitHub 再点 Packagist 的 submit 按钮。本地漏验这几步，90% 会导致“提交成功但包不可见”或“require 失败”。
-
composer validate：检查composer.json格式、必填字段、包名合法性（比如含大写字母就过不去） -
composer install --no-dev：模拟用户环境，确认src/下的类能被正常加载，没有依赖dev里的东西 -
git tag -a v1.0.0 -m "First release"：Packagist 只认带v前缀的语义化 tag，1.0.0或release-1.0都无效
为什么 Packagist 同步失败？常见卡点在哪
Packagist 不是自动监听 GitHub 的，你得手动 trigger 一次，而且它只认公开仓库 + 正确的 webhook 或手动 submit。最常踩的坑是权限和路径细节。
- GitHub 仓库必须是 public，private 仓库即使填了 token 也不会同步
- 首次提交到 Packagist 时，URL 必须精确到仓库根路径，例如
https://github.com/yourname/your-package，多一个/tree/main就失败 - 如果之前提交过同名包（哪怕删了），Packagist 会拒绝重复注册，得联系 support 清理，不能自己重试
- 提交后等 2–5 分钟再
composer require yourname/your-package，刚提交时 Packagist 还没抓取 tag
最麻烦的是命名空间和 vendor 名不一致——比如你在 Packagist 注册了 me/utils，但 composer.json 里写的是 "name": "myname/utils"，同步会静默失败，日志里只显示“package not found”。这个错没法从界面看出来，得去 Packagist 的 package 页面核对 URL 和 name 字段是否完全一致。
