Composer装Laravel包需协同composer.json、autoload.php与composer.lock：路径配置错误、锁文件缺失或框架升级不按指南操作，均会导致类加载失败或依赖冲突。

Composer 装 Laravel 包真方便，但得懂它怎么找包、锁版本、读 autoload

Laravel 本身是靠 composer 驱动的，所有官方包（比如 laravel/sanctum、laravel/breeze）和第三方包（如 spatie/laravel-permission）都走 composer require。它不是“装完就跑”，而是依赖 composer.json 和 vendor/autoload.php 两级联动——漏掉任一环节，类就找不到。

• composer require 默认写 "minimum-stability": "stable"，所以 dev-main 或带 -beta 的包要显式加 --stability=dev
• 装包时若提示 Root composer.json requires ... but it is not installable，大概率是 PHP 版本或 ext-* 扩展不满足，别急着删 composer.lock，先看报错里具体卡在哪个 require
• autoload 段写错路径（比如把 "psr-4": {"App\\": "app/"} 改成 "App\\": "app/Models/"），会导致模型类加载失败，且错误不直接报路径问题，只报 Class App\Models\User not found

laravel/framework 升级最容易翻车，别只改 composer.json

laravel/framework 不是普通包，它绑定了 php、symfony/*、doctrine/dbal 等一堆底层依赖。直接改 composer.json 里的版本号再 composer update，常会触发依赖冲突或静默降级。

• 升级前必须查对应版本的 官方升级指南，比如 Laravel 11 要求 PHP 8.2+，且移除了 bootstrap/app.php，硬升会报 Target class [App\Providers\AppServiceProvider] does not exist
• composer update laravel/framework 可能顺手更新 symfony/console 到不兼容版，建议加 --with-dependencies 显式控制范围，或用 composer update "laravel/framework" "symfony/*"
• 升级后务必清空 bootstrap/cache/ 下的 config.php、packages.php，否则旧配置缓存还在，新配置不生效

自定义包 autoload 写法不对，本地开发调试就失效

自己写包或抽离通用逻辑到 packages/ 目录时，很多人直接在 composer.json 加 path repo，但忘了配 autoload，结果 php artisan tinker 里 new MyPackage\Foo() 报错。

{
    "repositories": [
        {
            "type": "path",
            "url": "./packages/my-package"
        }
    ],
    "require": {
        "my-package/core": "*"
    },
    "autoload": {
        "psr-4": {
            "MyPackage\\": "packages/my-package/src/"
        }
    }
}

• repositories.type: path 只让 Composer 找到包，不等于自动加载；autoload 必须单独配，且路径相对于项目根目录
• 改完 composer.json 后要运行 composer dump-autoload，否则新增的命名空间不会进 vendor/composer/autoload_psr4.php
• 如果包里用了 __DIR__ . '/../config' 这种相对路径，发布到 packagist 后会崩，本地测试没问题不代表线上可用

composer.lock 提交与否，直接影响团队环境一致性

composer.lock 不是可选文件。Laravel 项目里它锁死了每个包的精确版本、哈希值、安装路径，没它，composer install 就退化成 composer update，不同人 install 出来的依赖可能差一个小版本，导致行为不一致。

• CI/CD 流程里必须用 composer install --no-dev（生产环境）或 composer install（本地），不能用 update，否则绕过 lock 文件
• 删了 composer.lock 后执行 composer install，会重新生成 lock，但此时所有包取最新兼容版，不是原来那套——相当于重装依赖树
• 多人协作时，有人 require 新包但忘了提交 composer.lock，别人 git pull 后 composer install 会装错版本，典型症状是 php artisan migrate 报未知迁移类

依赖管理的麻烦点不在命令多，而在每步操作背后都有隐含约束：autoload 配置、lock 文件效力、框架与组件的语义化版本边界。漏掉一个，报错信息往往不指向根源。