必须用 repositories + path 类型仓库将外部代码纳入 composer 自动加载——因直接 require 不触发 psr-4 映射、不被 dump-autoload 扫描，且无法享受依赖管理；本地包需含完整 composer.json（name、autoload、version 三者严格对齐），配置后须运行 composer update。
不能靠改 vendor-dir 或命令行参数把外部代码“塞进”自动加载范围——必须用 repositories + path 类型仓库，且本地包的 name、路径、autoload 配置三者必须对齐。
为什么 require './lib/my-utils' 不行，而要用 repositories？
Composer 的自动加载机制只认它自己管理的包。直接 require 一个本地文件，既不会触发 PSR-4 映射，也不会被 dump-autoload 扫描，更无法享受依赖解析、版本约束或脚本执行等能力。你写的函数/类在 CLI 或 Web 请求中可能“偶现可用”，但一旦换环境（如 CI）、换 PHP 版本或加了 OPcache，就大概率报 Class not found 或 Call to undefined function。
真正可控的方式是让 Composer “认为”那个目录就是一个合法包。
- 本地目录必须有完整的
composer.json（含name、autoload、至少一个version或"minimum-stability": "dev"） -
name必须和你在项目中require的字符串完全一致（大小写敏感） -
autoload必须正确声明命名空间或文件路径，否则dump-autoload不会注册它
怎么配 repositories 才让 path 仓库生效
配置必须写在项目根目录的 composer.json 最外层 repositories 数组里，不是 extra，也不是 require 下面：
{
"repositories": [
{
"type": "path",
"url": "./packages/my-utils"
}
],
"require": {
"mycompany/utils": "*"
}
}
关键细节：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
-
url是相对于当前composer.json的路径，不能以/开头，也不能用file://或绝对路径 - 如果
./packages/my-utils/composer.json里写的是"name": "mycompany/utils"，那require字段就必须一模一样 - Windows 下路径分隔符不用手动改，Composer 会自动处理；但别用
.packages...这种写法，统一用/ - 配完后必须运行
composer update mycompany/utils或全量composer update，install不会重新解析repositories
autoload 失败的常见原因和修复点
装上了但类还是找不到，90% 不是 Composer 问题，而是 autoload 配置没闭环：
- 本地包的
composer.json里没写"autoload": {"psr-4": {"MyCompany\Utils\": "src/"}}—— 补上并运行composer dump-autoload - 用了
"files"字段（比如"files": ["helpers.php"]），但helpers.php路径是相对于该包自己的composer.json，不是项目根目录 - PHP 文件里写了
namespace，但文件实际放在src/Utils/Helper.php，而 autoload 写的是"MyCompany\Utils\": "src/"—— 此时类名应为MyCompanyUtilsUtilsHelper，容易多嵌一层 - 开发时开了 OPcache，改了
composer.json或文件结构后没清缓存：php -r "opcache_reset();"
团队协作时最易忽略的硬编码陷阱
本地开发时用 "./packages/my-utils" 没问题，但 CI 流水线拉代码时这个路径根本不存在。不要指望 git submodule 或人工同步来兜底。
可行做法只有两种：
- CI 中用脚本先
git clone对应仓库到固定路径，再跑composer update - 把本地包发布到私有 Packagist（如 Satis 或 Private Packagist），然后改
repositories为"type": "composer", "url": "https://your-private-repo.com"—— 这才是可复现、可审计的路径
任何带 ../、$HOME、环境变量插值（如 ${MY_PKG_PATH}）的 url 值，在 Composer 里都会静默失效，连 warning 都不抛。
