90%失败源于Docker未启用symlink权限、挂载路径与url不一致或本地包composer.json缺"options":{"symlink":true}；容器内"../my-pkg"指向镜像内部而非宿主机，必须-v显式挂载且路径严格对齐，否则vendor为空或报“Could not find package”。
容器里用 Composer path 仓库挂载本地包，90% 失败是因为 symlink 权限没开、路径挂载错或 options 没配对——不是配置逻辑有问题，而是 Docker 默认不支持符号链接，且挂载路径和 composer.json 里的 url 必须严格对齐。
为什么 docker run 后 vendor 里是空的或报 “Could not find package”
根本原因不是 Composer 没读到 repositories，而是容器内根本访问不到你声明的 url 路径。Docker 容器默认隔离文件系统，"url": "../my-pkg" 在容器里指向的是镜像内部的上层目录（通常不存在），而不是宿主机的对应位置。
- 必须显式用
-v或docker-compose.ymlvolumes 将本地包目录挂载进容器，且挂载路径要和url值完全一致（例如：宿主机../my-pkg→ 容器内也得是../my-pkg） - 挂载点权限需开放读取，否则 Composer 解析
composer.json时静默跳过该仓库 - 如果用了通配符如
"url": "../packages/*"，每个子目录都得单独挂载，或改用 bind mount 整个../packages目录 - Windows/macOS 用户注意：Docker Desktop 的文件共享设置必须启用对应路径，否则挂载后目录为空
symlink 在容器里创建失败的三个硬性条件
即使挂载成功，vendor/vendor/name 仍是复制而非链接，大概率是以下任一条件未满足：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- Docker 运行时未加
--cap-add=SYS_ADMIN（Linux 宿主机必需；macOS/Windows Desktop 默认绕过但仍有概率 fallback） - 本地包自己的
composer.json缺少"options": {"symlink": true}—— 主项目配了没用，必须本地包自己声明 - 挂载方式用了
:ro（只读）或 overlayfs 不支持 symlink，导致 Composer 自动降级为 copy
验证是否真用了链接：docker exec -it myapp ls -la vendor/vendor/name。输出含 -> 才算成功；若显示普通目录，说明 fallback 已发生，改代码不会生效。
docker-compose.yml 中 path 仓库的正确写法
不要在 build 阶段硬编码路径，而应在运行时通过 volume 和环境隔离控制。推荐结构如下：
services:
app:
build: .
volumes:
- ./:/app
- ../my-pkg:/app/../my-pkg
# 注意：第二个挂载必须和 composer.json 里 "url" 的值完全相同
-
../my-pkg是相对于主项目composer.json的路径，挂载目标也必须是/app/../my-pkg（即容器内/app是工作目录） - CI/CD 流水线中禁止保留
repositories的 path 条目，应通过构建参数或环境变量开关，例如用COMPOSER_REPOSITORIES='[]'覆盖 - 若多个本地包，避免逐个挂载，改用统一父目录挂载 +
"url": "./packages/*"，并确保每个子包都有合法composer.json
最易被忽略的一点：IDE 调试时断点不命中，往往不是 Xdebug 配置问题，而是容器内路径（/app/vendor/vendor/name）和宿主机真实路径（/Users/xxx/my-pkg）不一致，导致 IDE 无法映射。必须在 PHPStorm/Xdebug 配置里显式设置 path mapping，把 /app/vendor/vendor/name 对应到宿主机的挂载源路径。
