必须写"type": "path"和相对路径url（如"../my-package"），不能省略type或用错误值，url须指向含合法composer.json的目录，name与require严格一致，版本用dev-main。

repositories 配置里 type 和 url 怎么写才有效

必须显式声明 "type": "path"，不能省略或写成 "path"、"local" 等错误值。Composer 只认这个字符串，其他值会被忽略。

url 必须指向一个**目录**，不是 composer.json 文件本身；支持相对路径（如 "../packages/my-pkg"），不支持 ~/ 或环境变量（如 $HOME/packages）；Windows 下建议用正斜杠或双反斜杠，单反斜杠易被 JSON 解析器截断。

• 相对路径从项目根目录的 composer.json 所在位置开始计算
• 若用通配符（如 "../packages/*"），每个匹配子目录都必须含独立的 composer.json
• 路径不存在时，composer install 会直接报错，不会跳过或尝试 fallback

本地包的 composer.json 必须包含哪些字段

仅靠目录存在不够，本地包自身的 composer.json 必须有 name 和 version 字段，且 name 必须与你在项目中 require 的完全一致（包括 vendor 名，大小写敏感）。

version 不必是语义化版本；开发阶段推荐写 "dev-main" 或 "dev-develop"，避免因缺少 tag 导致 composer require vendor/name:* 匹配失败。

Academic Composer Upload

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

下载

• 如果本地包没 Git 仓库，version 字段仍需存在，否则 Composer 拒绝识别
• autoload 字段可为空对象 {}，但不能缺失（否则类自动加载失效）
• 不要在本地包中写 "repositories" —— 它只由使用方（主项目）定义

怎么控制 symlink 还是 copy，以及为什么默认行为不一致

Linux/macOS 默认创建符号链接，Windows 默认复制文件 —— 这不是 bug，而是 Composer 基于系统能力做的保守选择。是否启用 symlink 由两个条件共同决定：操作系统支持 + 配置显式允许。

要统一行为，必须在 path 仓库配置中加 "options": {"symlink": true}（强制软链）或 {"symlink": false}（强制复制）。不写 options 时，Windows 下永远不 symlink。

• CI/CD 环境必须设 "symlink": false，否则构建必然失败（路径不存在 + 权限限制）
• 符号链接生效后，改本地代码无需 composer dump-autoload，项目内立刻可见变更
• 想验证是否真链接成功？运行 ls -la vendor/vendor/name（Linux/macOS）或 dir vendor\vendor\name（Windows），输出含 -> 或 <symlink></symlink> 即为成功

为什么 composer install 不更新已有链接，而 update 可以

composer install 只按 composer.lock 还原状态，它不重新解析依赖图；即使你改了本地包的代码、甚至移动了目录，只要 lock 文件没变，它就什么也不做。

composer update vendor/name 才会重新读取 repositories，校验路径、匹配 name、检查本地 composer.json，并重建 symlink —— 这才是“刷新链接”的正确操作。

• 全量 composer update 很慢，且可能意外升级其他包；务必指定包名
• 首次 composer require vendor/name:dev-main 会触发 symlink 创建，等价于一次带目标的 update
• 如果 link 指向的路径已不存在，update 会报错，而不是静默降级到 dist 包

实际协作中最容易被忽略的一点：path 仓库配置不能进生产环境。它不是“备用源”，而是“覆盖源”——一旦存在，Composer 就只认它，且不提供自动 fallback。上线前必须删掉或通过构建脚本动态剔除 repositories 中的 path 条目，否则部署直接中断。