答案是必须配置path仓库并严格对齐name、路径与版本：在项目根composer.json的repositories中添加type为path的相对路径源，本地包需含合法composer.json且name与require完全一致，version用dev-main等分支名约束。
本地开发时怎么让项目立即加载自己的扩展包
直接 composer require 会失败，因为 Packagist 上没有你的包。必须用 path 类型仓库把本地目录“映射”进项目依赖体系。
在项目根目录的 composer.json 的 repositories 数组里加一项：
{
"type": "path",
"url": "./packages/my-utils"
}
注意三点：repositories 必须是根级数组；url 用相对路径（不能带 file:// 或 ~/）；./packages/my-utils 目录下必须有合法的 composer.json，且含 "name": "myorg/utils" 字段。
- 本地包的
composer.json中version建议写"dev-main"，require 时就得写"myorg/utils": "dev-main"，写"^1.0"会找不到 - 改完
repositories后，先运行composer config --list确认配置已加载，再执行composer require myorg/utils - 如果报
Could not find package，八成是本地包的name和require里的名字大小写不一致，或路径多了一级/少了一级
autoload 配置写错会导致类找不到，但错误不报在安装阶段
装进 vendor/ 不等于能 use。90% 的 Class not found 是 autoload 映射没对上。
本地包自己的 composer.json 必须声明 psr-4，例如：
"autoload": {
"psr-4": {
"MyOrg\Utils\": "src/"
}
}
这个配置要求：命名空间末尾必须有反斜杠 ；路径值末尾必须有斜杠 /；大小写必须和实际文件路径、namespace 声明完全一致。
-
src/Helper.php里写namespace MyOrgUtilsHelper;是错的，应为namespace MyOrgUtils;，否则自动加载器找不到文件 - 改完
autoload后，必须运行composer dump-autoload（开发阶段不用-o），否则新规则不生效 - IDE 提示 “Undefined class” 但代码能跑通？大概率是 IDE 没读到你本地包的
autoload，确认项目是否引入了vendor/autoload.php，并重启 IDE 触发重索引
发布到 Packagist 前必须检查的三个硬性条件
Packagist 不校验代码逻辑，只认三件事：名字唯一、composer.json 合法、Git 仓库可公开访问。漏一，submit 就失败或包不可见。
-
"name"字段必须是vendor/package格式，全小写，只含字母、数字、中划线、下划线，例如"apptut/web-util"；"Apptut/WebUtil"或"apptut/webutil"都会被拒 -
autoload字段不能空，哪怕只是{"psr-4": {"": "src/"}}（适用于无命名空间的函数库） - GitHub/GitLab 仓库必须设为 public，且主分支（
main或master）根目录下必须有有效的composer.json——Packagist 不拉取 tag 或其他分支
提交后，Packagist 会自动抓取，但首次索引可能延迟几分钟。别急着 composer require，先去官网搜你的包名确认已收录。
CI 环境下 path 仓库根本不起作用，为什么
本地能跑通，CI 报 Could not find package，不是配置问题，是路径失效。
path 仓库依赖文件系统路径，而 CI 环境通常清空工作目录、不保留 ./packages/ 子目录。它只认远程 Git 仓库。
- CI 中禁用
path仓库，改用vcs类型，指向你的 GitHub/GitLab 地址，并确保该仓库有dev-main分支 - CI 脚本里加
composer install --no-dev --prefer-dist --optimize-autoloader，漏掉--optimize-autoloader，PSR-4 映射不会生成优化表，大项目启动慢甚至类加载失败 - 如果必须用本地路径（比如私有内网 CI），需在 CI 配置中显式
git clone你的扩展包到固定路径，并确保composer.json中url指向该绝对路径（CI 容器内路径）
最常被忽略的是：你在本地开发时 require 的是 dev-main，但 CI 拉的是 main 分支的最新 commit，如果还没 git push，就会加载不到最新代码。
