一个可复用的 Composer 扩展包必须满足三个硬性条件：composer.json 含合法 name、autoload 和 type 字段；主项目通过 path 仓库显式引用；每次修改后须执行 composer update vendor/name 刷新链接，缺一不可。
直接上结论：一个可复用的 Composer 扩展包，不是写完类就能被 require 进来的——它必须满足三个硬性条件：composer.json 里有合法 name、autoload 和 type；主项目通过 path 仓库显式引用；每次改代码后必须运行 composer update vendor/name 刷新链接。缺一不可。
本地包的 composer.json 必须包含哪些字段
很多开发者把代码丢进目录就跑 composer update，结果报 Could not find package。根本原因在于本地包根目录下的 composer.json 缺关键字段：
-
name必须和主项目require中写的完全一致（包括大小写、斜杠方向），例如"acme/my-widget" -
type建议显式写"library"或"laravel-package"（Laravel 项目）或"yii2-extension"（Yii 2 项目），否则 Composer 可能跳过自动发现逻辑 -
autoload至少要有psr-4映射，例如{"Acme\MyWidget\": "src/"}；空配置或只写files不足以支撑常规使用 -
version不能省略，写"dev-main"或"1.0.x-dev"即可，这是 Composer 解析本地分支的依据
主项目怎么正确引用本地包
主项目不配 repositories，Composer 就当本地包不存在。常见错误是把 repositories 写在本地包自己的 composer.json 里，或者路径写错层级：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
-
repositories必须写在主项目的composer.json根级，格式为：[{"type": "path", "url": "../my-widget"}] -
url必须指向**包含composer.json的目录**，不是它的父目录，也不是src/子目录 -
require中写"acme/my-widget": "*"，而不是"acme/my-widget": "dev-main"——*表示“取本地最新元信息”，最稳妥 - Windows 下避免绝对路径（如
C:/work/my-widget），改用相对路径（如"../my-widget"），否则可能静默失败
改了代码为什么主项目没反应
这是最常被误解的一点：path 仓库不会实时挂载。Composer 默认行为是把本地包内容复制进 vendor/ 目录（非 symlink），所以你改了 src/ 下的类，主项目根本读不到新代码：
- 执行
composer update acme/my-widget（不是install，也不是全量update）才能刷新 - 想真正实现“改完即生效”，需在
repositories条目中加"options": {"symlink": true}（Linux/macOS 默认开启，Windows 必须显式写且以管理员权限运行命令行） - 验证是否成功：Linux/macOS 运行
ls -la vendor/acme/my-widget，应看到->指向源目录；Windows 运行dir vendorcmemy-widget，应显示为“快捷方式”类型 - 如果 CI 环境不支持 symlink，可在
composer.json中设"preferred-install": {"acme/my-widget": "dist"}强制复制模式
PSR-4 自动加载为什么总失效
类找不到，90% 是命名空间与路径没对齐。别只看 autoload 配置，要逐层核对：
- 文件路径
src/Widgets/DatePicker.php对应的命名空间必须是AcmeMyWidgetWidgets（注意末尾反斜杠） - 类名必须是
DatePicker，且首字母大写，与文件名严格一致 - 执行
composer dump-autoload -o生成优化映射表，但前提是autoload配置本身已正确 - 检查
vendor/composer/autoload_psr4.php是否已生成对应条目；没有的话，说明composer.json的 autoload 部分未被识别
最容易被忽略的是：本地包目录下如果没有 git init 或至少一个 commit，Composer 会直接跳过该目录——它把 git 状态当作“包已就绪”的隐式信号。哪怕只是开发阶段，也建议初始化 git 并做一次空 commit。
