答案是：Composer严格匹配本地包composer.json的name字段与主项目require声明，大小写、斜杠、短横线必须完全一致；repositories须在主项目根composer.json顶层数组中配置type:"path"及相对路径url。

本地包必须有合法 composer.json，且 name 与主项目 require 完全一致

Composer 不会“猜”包名，它只严格比对本地包 composer.json 中的 name 字段和主项目 require 里写的字符串。大小写、斜杠方向、vendor 名都必须一模一样。

• 本地包 composer.json 必须存在，且语法合法（可用 composer validate 检查）
• name 如 "acme/utils"，主项目 require 就得写 "acme/utils": "dev-main"，不能是 "Acme/Utils" 或 "acme/utils-dev"
• 如果本地包目录下没有 composer.json，或 name 字段缺失/拼错，Composer 会静默跳过该路径，转头去 Packagist 找，报 Could not find package

repositories 必须写在主项目 composer.json 根级，url 用相对路径

配置位置错，等于没配。Composer 只读取项目根目录下 composer.json 文件最外层的 repositories 数组，其他任何嵌套位置（比如塞进 config 或 extra 里）全部忽略。

• 正确写法："repositories": [{ "type": "path", "url": "../acme-utils" }]
• url 必须是相对于主项目 composer.json 的路径，不支持 file://、~/、$HOME 或绝对路径（如 /Users/xxx/acme-utils）
• Windows 下建议统一用 / 作分隔符（如 ../acme-utils），避免 引发解析异常

启用 symlink 需显式声明，且仅 composer update 生效

默认行为是复制（copy），不是链接（symlink）。改了本地代码不生效？八成是还在 copy 模式。

Academic Composer Upload

辅助学术写作，包括查找资料、生成大纲、引用扩写及润色风格，同时确保引用规范。

下载

• 必须在本地包自己的 composer.json 根级加："options": {"symlink": true}（注意：不是主项目的配置）
• Windows 用户需以管理员身份运行终端，或已开启“开发者模式”，否则 symlink 会静默 fallback 到 copy
• composer install 不创建 symlink，它只按 composer.lock 复制；只有 composer update acme/utils 才会重新解析并尝试建链
• 验证是否成功：ls -la vendor/acme/utils（macOS/Linux）或 dir vendorcmeutils（Windows），输出中必须含 -> 或

autoload 修改后必须手动 composer dump-autoload

软链建好了，代码也改了，但类还是找不到？大概率是自动加载器没更新。

• 本地包 composer.json 中的 autoload（如 "psr-4": {"Acme\Utils\": "src/"}）只在 dump-autoload 时写入 vendor/composer/autoload_psr4.php
• 新增命名空间、改了 src/ 结构、加了新类——这些操作后，必须在主项目中运行 composer dump-autoload
• 不要依赖 composer update 自动触发 autoload 更新；它只在安装/更新包时顺带执行一次，不保证覆盖所有变更

实际开发中，最容易被忽略的是本地包未执行 git init 并提交至少一个 commit——Composer 2.2+ 会因此拒绝 symlink，且不报错，直接 fallback 到 copy。这个限制没有文档高亮，但真实存在。