必须用path仓库而非composer require远程包，因后者安装已打包版本（如v1.0.0），每次修改需提交、打tag、update，效率低；path仓库通过软链接将本地目录映射至vendor/，改保存即生效。

为什么必须用 path 仓库而不是 composer require 远程包

本地改代码后要立刻在 Laravel 项目里验证，composer require vendor/package 拉的是已打包的版本（比如 v1.0.0），每次修改都得 composer update + 提交 Git + 打新 tag，效率极低。path 仓库让 Composer 把本地目录当“源”，直接 symlink 进 vendor/，改完保存就能刷新测试。

常见错误现象：composer require acme/demo:@dev 后类还是找不到、php artisan vendor:publish 列不出配置——多半是没走 path，而是真去 Packagist 拉了空壳包。

• 必须在 Laravel 项目的 composer.json 里加 repositories 段，不能只在包自己的 composer.json 里写
• url 值必须是**绝对路径或相对于 Laravel 项目根目录的相对路径**，比如 "../packages/acme/demo"；Windows 用户注意斜杠方向不影响，但路径不能含空格或中文
• 加完后要运行 composer update acme/demo --with-dependencies，不是 install，否则不会重建 symlink

path 仓库的 composer.json 怎么配才不报错

被 symlink 进来的包，其 composer.json 必须能独立通过 Composer 校验，否则 update 阶段直接失败。最容易漏的是 autoload 和 name 字段。

典型报错：[InvalidArgumentException] Package acme/demo has a PHP requirement incompatible with your PHP version 或 Could not find package acme/demo——其实是包自己的 composer.json 缺 require.php 或 name 格式不对。

• name 必须带 vendor，如 "acme/demo"，不能是 "demo"
• autoload 至少要有 psr-4，且命名空间与目录严格对应，例如 "Acme\Demo\": "src/" → 类文件必须在 src/ 下，且命名空间以 Acme\Demo\ 开头
• require 里建议显式声明 "php": "^8.1"（Laravel 10+ 最低要求），避免和主项目 PHP 版本冲突
• 别写 "type": "laravel-package" 就以为自动发现会生效——它只是个提示，真正起作用的是 extra.laravel.providers 或自动发现规则

改完包代码，Laravel 项目里为什么还是旧行为

path 仓库虽然用了 symlink，但 Laravel 的类加载、配置合并、命令注册等依赖多个缓存层，改代码 ≠ 立刻生效。

Laravel

避免常见的Laravel错误：N+1查询、批量赋值、缓存陷阱及队列序列化陷阱。

下载

常见表现：Service Provider 的 boot() 里加了 dd('new')，刷新页面没反应；或 php artisan list 里看不到新命令。

• 先跑 composer dump-autoload -o，强制刷新所有 autoload 映射（包括 symlink 目录）
• 再跑 php artisan package:discover，触发 Laravel 重新扫描 vendor/composer/installed.json，把你的包加进服务提供者列表
• 如果用了 config:cache，记得 php artisan config:clear，否则 mergeConfigFrom() 不会重新执行
• 视图、迁移、路由等静态资源不会自动重载，需手动 php artisan view:clear 或 php artisan migrate

path 仓库和 composer link 冲突怎么办

composer link 在 Laravel 10+ 和 Windows 上极易出问题：它会修改全局 vendor/autoload.php，导致多个项目间 autoload 冲突，甚至让 dump-autoload 失效。path 是目前唯一稳定方案。

如果你之前试过 link，现在切回 path，务必清理残留：

• 删掉 Laravel 项目 vendor/ 下对应包的目录（如 vendor/acme/demo）
• 检查 composer.json 里有没有 "acme/demo": "dev-master" 这种没加 @dev 的旧 require 条目，删掉或改成 "@dev"
• 运行 composer update --lock，确保 composer.lock 中该包的 type 是 path，不是 package
• 最后确认 vendor/acme/demo 是个 symlink，指向你本地包目录，而不是普通文件夹

复杂点在于 symlink 的生命周期完全由 Composer 控制，不是你手动 ln -s 就行；一旦 composer update 被误触发全量升级，它可能悄悄替换成远程包——所以开发中永远用 composer update vendor/package 精确控制。