本地路径源必须置于repositories数组首位，否则Composer会先向远程镜像发起无效请求并超时等待；需配"type": "path"、合法composer.json及严格匹配的name字段，并显式设"packagist.org": false禁用官方源。
本地路径源必须放在repositories数组首位
Composer 查找包时严格按 repositories 数组顺序遍历，一旦某个源返回 404 或元数据不匹配，就跳到下一个。如果你把阿里云镜像放前面、本地路径放后面，composer require my/local-package 会先去远程镜像查——结果当然是 404，然后才轮到本地路径，但此时已触发了不必要的网络请求和超时等待。
正确做法是把本地源声明为第一个元素：
"repositories": [
{"type": "path", "url": "./packages/my-local-package"},
{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"},
{"packagist": true}
]
注意三点：
-
type必须是"path"（不是"package"或"vcs"），且url是相对或绝对文件路径，不能带协议 - 路径末尾不加斜杠，但目录内必须含有效的
composer.json文件（版本号、name 字段不可为空） - 如果路径含空格或中文，Windows 下需用双引号包裹整个字符串，Linux/macOS 一般无感
国内镜像 URL 必须带末尾斜杠且类型为 composer
阿里云、腾讯云等镜像地址若漏掉末尾 /，Composer 会错误拼接成 https://mirrors.aliyun.com/composer/packages.json（少一级路径），直接返回 404；而 type 值写错（如 "type": "git"）会导致该条目被完全忽略，静默 fallback 到 packagist.org。
验证是否生效最直接的方式是运行：
composer config repo.packagist
输出必须是完整 JSON 对象，例如：
{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}
常见失效组合：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
-
composer config -g packagist（1.x 写法，2.x 不识别） -
composer config -g repo.packagist https://mirrors.aliyun.com/composer（缺composertype 参数） -
composer config -g repo.packagist composer http://mirrors.aliyun.com/composer/（HTTP 协议在新版中可能被拒绝）
混合模式下 packagist.org 必须显式禁用
即使你写了 {"packagist": true} 在数组末尾，只要项目级 composer.json 中没同时设置 "packagist.org": false 同级字段，Composer 仍会在所有自定义源查完后，自动追加一次对官方源的请求——这对本地开发毫无意义，还拖慢 composer update 速度，尤其在 DNS 不稳的环境里容易卡住。
所以完整结构应为：
"repositories": [
{"type": "path", "url": "./packages/my-local-package"},
{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"},
{"packagist": true}
],
"packagist.org": false
这个 "packagist.org": false 是独立顶层字段，不是 repositories 的子项，位置任意，但必须存在。它告诉 Composer：别再偷偷摸摸连官方源了。
require 本地包时 name 必须与路径内 composer.json 严格一致
很多人执行 composer require myvendor/mypackage 失败，不是镜像问题，而是本地 ./packages/my-local-package/composer.json 里写的 "name" 是 "myvendor/my-package"（多了短横）或大小写不一致（MyVendor/MyPackage）。
Composer 的 path 源不支持模糊匹配，name 字符串必须逐字相等。调试方法：
- 进入本地包目录，运行
composer validate确保composer.json合法 - 检查
name是否符合vendor/name格式，不含空格、大写字母、下划线 - 执行
composer show myvendor/mypackage，如果报Could not find package，说明 name 不匹配或路径未被识别
路径源不会自动注册 autoload，你仍需在根项目的 autoload 或 autoload-dev 中手动加映射，否则类找不到。
