必须用 composer require 安装 ThinkPHP 扩展包，因 install 仅复原 lock 文件、update 可能误升核心框架；装完需检查 vendor 目录、注册服务提供者、复制配置文件并执行 dump-autoload。
必须用 composer require，别碰 install 或 update
装新扩展包只认 composer require vendor/package-name。用 composer install 看起来没报错，但 vendor/ 里压根不会出现你要的包；composer update topthink/think-captcha 表面只写了一个包名，实际可能把 topthink/framework 升到不兼容版本，导致路由或命令失效。
常见错误现象：
- 执行完命令后
ls vendor/topthink/没有对应目录 -
use thinkcaptchaCaptcha;报Class not found - 终端显示 “Package installed”，但项目里完全无反应
实操要点：
- 确认当前路径下存在
composer.json和public/目录——这是项目根目录，不是public/或vendor/ - 指定版本时用冒号语法：
composer require topthink/think-filesystem:^2.0，@符号无效，=在新版 Composer 中可用但不推荐 - 装完立刻检查
vendor/topthink/think-captcha/是否存在，不存在说明根本没装进去
服务提供者没注册，装了也白装
ThinkPHP 6/7/8 的扩展依赖 Service Provider 注册才能生效。仅下载代码不等于能调用 Captcha::create() 或 app('filesystem')。
立即学习“PHP免费学习笔记（深入）”；
检查步骤：
- 打开
config/app.php，确认'providers' => []数组里有对应类，例如：thinkcaptchaCaptchaService::class - 检查
composer.json是否含"dont-discover": ["*"]—— 这行会全局禁用自动注册，删掉或改成具体排除项（如["laravel/framework"]） - 部分扩展（如
think-queue、think-swoole）不自动注册，必须手动加
如果加了但还是不生效，运行 php think clear 清缓存，再试一次。
配置文件没复制，运行就报错
很多扩展包（比如 think-queue、think-filesystem）安装时不自动发布配置文件。缺了 config/queue.php 或 config/filesystem.php，启动时直接抛异常。
操作方式很直接：
- 定位源配置：例如
vendor/topthink/think-queue/config/queue.php - 复制到项目根目录下的
config/子目录中，路径必须是config/queue.php，不能放错层级 - 别指望“自动创建”——TP 不做这事，复制是硬性步骤
复制后无需额外命令，但改了配置要清缓存：php think clear 或删掉 runtime/cache/ 全部内容。
autoload 没刷新，类照样找不到
哪怕服务提供者和配置都对了，use think ilesystemFilesystem; 还是报错？大概率是 Composer 自动加载映射没更新。
原因可能是：
- 手动改过
composer.json的autoload段 - 扩展包本身 PSR-4 前缀和你
use的命名空间不一致（比如写成use thinkfilesystemFilesystem;少了反斜杠） - 老项目入口文件漏了
require __DIR__ . '/../vendor/autoload.php';
解决办法：
- 执行
composer dump-autoload -o（-o表示优化模式，生成 classmap 提升性能） - 检查
vendor/composer/autoload_psr4.php里是否有'think\filesystem\' => array($vendorDir . '/topthink/think-filesystem/src/') - 确认入口文件
public/index.php第一行就是require __DIR__ . '/../vendor/autoload.php';，路径不能写死
最常被忽略的是：扩展包的 autoload 配置是否真被 Composer 读取并写入映射——它不看你有没有装，只看你有没有“告诉它怎么加载”。
