ThinkPHP 8.0 的 Composer 自动加载是硬性前提，入口文件必须最先引入 vendor/autoload.php 且路径正确；自定义命名空间需在 composer.json 中显式配置 psr-4 映射并执行 composer dump-autoload -o 生效，否则类无法加载。
ThinkPHP 8.0 的 Composer 自动加载不是“可选功能”，而是项目启动的硬性前提——vendor/autoload.php 没被正确引入，连 thinkApp 都找不到，更别说你自己的类。
public/index.php 必须最先 require vendor/autoload.php
ThinkPHP 8.0 默认已按正确顺序写好，但手动迁移、升级旧项目或从 ZIP 启动时，这行极易被删或错位。错误顺序会导致 ThinkPHP 自己的加载器先注册，后续 Composer 的 PSR-4 规则被跳过，第三方包内依赖（比如 GuzzleHttpPsr7Request）直接报 Class not found。
- 确认入口文件
public/index.php中，require __DIR__ . '/../vendor/autoload.php';这行在require THINK_PATH . 'base.php';之前 - 路径必须真实存在：运行
ls -l ./vendor/autoload.php看文件是否可读；若项目根目录是/var/www/myapp，而入口里写的是../vendor/autoload.php，实际应为../../vendor/autoload.php - 别用
require_once多次引入——同一请求中重复加载会触发Cannot declare class
自定义命名空间必须显式声明并 dump-autoload -o
ThinkPHP 8.0 不自动扫描 app/ 目录，也不识别你随手写的 AppServiceUserService —— 即使文件放在 app/service/UserService.php，没配 autoload 就等于不存在。
- 编辑项目根目录的
composer.json，在"autoload": {"psr-4": {}}里加映射，例如："App\": "app/"（注意双反斜杠） - 立即执行
composer dump-autoload -o：-o不可省，否则开发中常因缓存未更新导致类“明明写了却找不到” - 类文件名必须与类名完全一致（
UserBase.php→class UserBase），命名空间必须严格匹配路径（app/base/UserBase.php→namespace appase;） - 抽象类、接口、Trait 加载规则完全相同，不特殊处理
vendor 下非标准库要手动补映射或 spl_autoload_register
有些老 SDK（如早期阿里云 OpenAPI 包）没写 composer.json autoload 段，或者类文件在 vendor/aliyun/openapi/src/ 但命名空间是 AliyunOpenApi，Composer 默认不会管。
立即学习“PHP免费学习笔记（深入）”；
- 首选方式：在项目
composer.json的"autoload": {"psr-4": {}}里加映射："Aliyun\OpenApi\": "vendor/aliyun/openapi/src/"，再跑一次composer dump-autoload -o - 临时救急：在
public/index.php顶部或app/common.php里用spl_autoload_register补漏，例如：
spl_autoload_register(function($class) {
if (strpos($class, 'Aliyun\OpenApi\') === 0) {
$file = BASE_PATH . '/vendor/aliyun/openapi/src/' . str_replace('\', '/', substr($class, 13)) . '.php';
if (is_file($file)) require_once $file;
}
});
注意：这种写法不能替代 PSR-4 映射，仅限调试或无法改 composer.json 的场景。
preload.php 不能直接 require vendor/autoload.php
想用 PHP 8.0+ 的 opcache.preload 提升性能？别把 vendor/autoload.php 塞进 preload 脚本里——它含大量闭包和条件逻辑，PHP 启动时会直接报错 Cannot preload class ... because it was already defined。
- 真正该 preload 的是具体类文件，路径来自
vendor/composer/autoload_classmap.php - 先运行
composer dump-autoload --classmap-authoritative --no-dev，生成权威类映射 - 在
preload.php中遍历该数组，拼出绝对路径后require，且只加载你业务强依赖的核心类（如App\、MyLib\），避开 CLI 工具类、测试类等副作用代码 - preload 脚本本身不能有动态判断（如
if (APP_ENV === 'dev')），否则 PHP 服务根本起不来
最常被忽略的一点：autoload 配置改完不运行 composer dump-autoload -o，等于什么都没做；而 dump 完不检查 vendor/composer/autoload_static.php 是否更新，就贸然上线，线上环境可能还在用旧映射。
