repositories必须位于composer.json根级且与require同级，url为相对路径并指向含合法composer.json的目录，name需小写vendor/name格式，version建议显式设为dev-main，autoload须在本地包中正确声明并执行dump-autoload。
repositories 必须写在 composer.json 根级
Composer 只读取项目根目录下 composer.json 最外层的 repositories 字段，写错位置就等于没配。常见错误包括：
- 把
repositories塞进require、autoload或config里 —— 完全不解析，也不报错 - 在本地包自己的
composer.json里写repositories—— 对主项目无效 - 用
composer config repositories.xxx写进全局配置 —— 默认不继承，主项目不会读
正确结构是和 require 同级，例如：
{
"repositories": [
{
"type": "path",
"url": "../my-utils"
}
],
"require": {
"myorg/utils": "*"
}
}
url 必须是相对路径且指向含 composer.json 的目录
url 不是文件路径，也不是 URL，而是从主项目 composer.json 所在位置出发的相对目录路径。它必须满足：
- 以
./或../开头（如"./packages/logger"、"../shared-lib"） - 末尾不能带斜杠（
"../pkg/"会静默失效） - 路径终点是一个目录，且该目录下存在合法的
composer.json（语法正确、无尾逗号、全双引号） - 不支持绝对路径（
C:devpkg或/home/user/pkg在多数场景下失败）
验证方式：在主项目根目录运行 ls -la ../my-utils/composer.json（Linux/macOS）或 dir ..my-utilscomposer.json（Windows），确认文件真实存在。
本地包的 name 和 version 必须与 require 严格匹配
Composer 对 name 大小写、分隔符、vendor 名全部敏感。写错一个字符，composer require myorg/utils:dev-main 就会报 Could not find package，且 composer show --all 里根本不会列出它。
-
name必须是vendor/name格式，不含空格或大写字母（"MyOrg/Utils"❌，应为"myorg/utils"✅） -
version字段建议显式写"dev-main"（尤其未初始化 Git 时），避免依赖分支推断 -
require中版本约束只能用"*"——^1.2.0、~1.2、@dev等语义化写法对 path 类型仓库无效 - 若本地包未初始化 Git，
dev-main可能不被识别；执行git init && git add . && git commit -m "init"可解决
autoload 映射要独立配置并手动刷新
装进 vendor/ 不代表类能自动加载。90% 的 Class not found 问题出在 autoload 配置或加载时机上：
- 本地包的
composer.json中必须声明autoload（如"psr-4": {"MyOrg\Utils\": "src/"}），注意双反斜杠和路径结尾一致性 - 如果测试类在
tests/下，且用了autoload-dev，映射末尾必须带反斜杠："MyOrg\Tests\": "tests/" - 运行
composer dump-autoload（开发阶段不用加-o），否则新映射不会写入vendor/composer/autoload_static.php - 别在
require 'vendor/autoload.php'之前new类，也别手动requireautoload 文件
symlink 是否生效、autoload 是否映射正确，这两个点最容易被跳过。改了本地代码却没反应，大概率卡在这两步里。
