Composer安装插件失败主因是包未注册Packagist、仓库未声明、无有效Git tag或autoload配置错误；需检查repositories、version、autoload字段并执行dump-autoload。

composer require 装插件时提示 “package not found”

不是所有 GitHub 项目都能直接 composer require，关键看它是否注册在 Packagist 上，或者你有没有手动加仓库源。

• 先去 https://www.php.cn/link/5d2e892c81e5fafc51ab0973879563a0 搜包名，比如 laravel/sanctum，能搜到才能直装
• 如果包只在 GitHub/GitLab 私有库，得先在 composer.json 的 repositories 字段里声明源类型和地址，例如：

  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/username/custom-package"
    }
  ]

• 私有包没开 composer install 权限、或没打 Git tag（尤其是 dev-main 这类分支别名未启用），也会报找不到 —— 检查它的 composer.json 里 version 是否为空，以及是否至少有一个带语义化版本的 tag（如 v1.0.0）

装插件后命令不生效：artisan 或 composer 命令没更新

Laravel 插件（如 spatie/laravel-permission）要注册 Service Provider 才能用 php artisan 命令；普通 Composer 插件（如 phpunit/phpunit）则依赖 bin 配置自动映射到可执行文件。

Academic Composer Upload

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

下载

• 检查插件文档是否要求手动添加 ServiceProvider 到 config/app.php 的 providers 数组（Laravel 5.5+ 多数支持自动发现，但某些旧版或自定义包仍需手动）
• 运行 composer dump-autoload 确保类映射刷新，尤其改过 composer.json 后没重装依赖时
• 确认插件的 composer.json 里是否有 bin 字段（如 "bin": ["phpunit"]），没有的话，vendor/bin/ 下不会生成对应可执行文件

插件依赖冲突：require 和 require-dev 混用出问题

有些插件既是开发期工具（如 phpstan/phpstan），又会被其他包间接 require 进生产环境，导致版本打架或部署失败。

• 判断用途：静态分析、测试、代码生成类工具一律走 composer require --dev，避免污染生产 autoload
• 如果插件文档写明“仅用于开发”，但你的 composer install --no-dev 部署时仍报错，说明它被某个生产依赖硬依赖了 —— 用 composer depends <package></package> 查谁拖进来的
• 不要为绕过冲突强行加 --ignore-platform-reqs，PHP 版本、扩展缺失等真实兼容性问题会在线上爆发

插件安装后 vendor/autoload.php 不加载新类

常见于自定义命名空间未正确配置、PSR-4 映射路径错误，或插件本身没申明 autoload 规则。

• 打开插件根目录下的 composer.json，确认有类似这样的 autoload 块：

  "autoload": {
    "psr-4": {
      "Vendor\Package\": "src/"
    }
  }

• 如果你自己写了个本地插件并用 path 仓库方式引入，记得在主项目的 composer.json 中补上对应 autoload 映射，否则 dump-autoload 不会扫进去
• 执行 composer show <vendor></vendor> 看实际安装路径，再对照 vendor/composer/autoload_psr4.php 里是否已写入该映射 —— 没写入就说明 autoload 配置没生效

Composer 插件机制本身不复杂，真正卡住人的往往是包元信息（composer.json）里的 autoload、repository、version 这三处细节，漏一个，就等于没装上。