必须在项目根目录 composer.json 的顶层 repositories 数组中配置 type 为 path 的本地包路径，且本地包需含合法 composer.json（含匹配的 name 字段）、已初始化 Git 并有 commit，require 版本须精确对应分支名如 dev-main。
必须在项目根目录的 composer.json 里写 repositories 数组，且类型为 path，否则 Composer 根本不认本地包。
repositories 必须写在项目根 composer.json 的顶层
Composer 只读取项目根目录下 composer.json 文件最外层的 repositories 字段。写在子目录、依赖包自己的 composer.json 里，或嵌套在 extra、config 下，全部无效。
常见错误现象：composer require acme/utils 报 Could not find package acme/utils at any version，其实不是网络问题，而是配置压根没被加载。
- 正确写法（项目根
composer.json）：
{
"repositories": [
{
"type": "path",
"url": "./packages/my-utils"
}
],
"require": {
"acme/utils": "dev-main"
}
}
-
url必须是相对路径（如./packages/my-utils），不能带file://，也不能用~/或$HOME—— Composer 不解析环境变量 - Windows 下若用绝对路径，必须带盘符（如
C:/projects/my-utils），但推荐统一用相对路径避免跨平台问题
本地包目录必须满足三个硬性条件
就算 repositories 配对了，只要本地包目录缺以下任一条件，Composer 就静默跳过，不报错也不提示。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 目录下存在合法的
composer.json（语法正确，且含name字段） -
name字段值必须和你在主项目中require的完全一致（大小写敏感，比如"acme/utils"≠"Acme/utils"） - 该目录已运行
git init并至少有一个 commit；否则 Composer 拒绝识别分支名（如dev-main）
如果还没初始化 Git，可在本地包的 composer.json 中显式加 "version": "dev-main" 临时绕过。
require 时版本号必须匹配分支名，不能用通配符
Composer 对 path 类型仓库只认明确的开发分支标识，"*@dev"、"^1.0" 这类约束会直接让 Composer 回退到 Packagist 查找，导致本地路径失效。
- 进本地包目录执行
git branch --show-current，确认当前分支是main还是master - 主项目中
require写死对应分支：如"acme/utils": "dev-main"或"acme/utils": "dev-master" - 若本地包
composer.json中写了"minimum-stability": "stable"，需同步在主项目中设"minimum-stability": "dev"，否则dev-main会被稳定性策略过滤掉
改了本地包代码，主项目没更新？先看是不是复制模式
Composer 默认对 path 仓库尝试创建符号链接（symlink），但 Windows 下常因权限或策略限制 fallback 到复制模式（copy）。此时修改本地包不会自动同步到 vendor/ 下的副本。
- 检查
vendor/acme/utils是文件夹还是快捷方式（Windows）或软链（Linux/macOS） - Windows 下需以管理员身份运行终端，或启用“开发者模式”并允许创建符号链接
- 不想折腾 symlink？可手动删掉
vendor/acme/utils后再跑一次composer install，强制重拉
真正容易被忽略的是：即使所有配置都对，只要本地包目录权限受限（比如 OneDrive 同步文件夹、NTFS 加密、WSL 跨文件系统挂载），Composer 就可能读不到内容，最终静默失败。
