ThinkPHP 6 手动加载非 Composer 类库的正确姿势是：将类文件放入 app/library/ 并声明命名空间，再在 app/provider.php 中注册路径（如 'applibrary' => app_path('library')）；若需短名映射，同步添加类名映射（如 'QrCode' => 'applibraryQrCode'）；无命名空间旧类只能按需 include_once；手动类无法覆盖同名 Composer 类，应通过容器绑定覆盖。
ThinkPHP 6 手动加载非 Composer 类库的正确姿势
不能直接 require 或 include 第三方类文件，TP6 的自动加载机制默认只认 app、vendor 和 PSR-4 注册路径。硬塞一个 require_once 'xxx.php' 看似能跑通，但会破坏命名空间解析、无法被容器识别、热更新失效，后续调用 App::make() 或依赖注入时直接报 Class not found。
实操建议：
- 把第三方类库（比如
phpqrcode或某个纯.php工具类）统一放到app/library/下（如app/library/QrCode.php），保持目录清晰 - 确保该类有明确的命名空间，例如
namespace applibrary;，不要用空命名空间 - 在
app/provider.php中手动注册其所在路径：return [ 'app\library\' => app_path('library'), ]; - 之后就能像原生 TP 类一样使用：
use applibraryQrCode;，TP 自动加载器会按 PSR-0 规则匹配到文件
类库映射（alias）只适用于已知完整类名的静态绑定
类库映射不是“别名替换”，而是告诉框架：“当有人写 QrCode 这个短名时，请当成 applibraryQrCode 去加载”。它不解决路径发现，也不触发自动扫描，只是字符串映射。
常见错误现象：
立即学习“PHP免费学习笔记（深入）”；
- 写了映射但依然报
Class 'QrCode' not found—— 因为映射前没确保类文件已被自动加载器识别（即上一步的路径注册没做） - 映射写成
'QrCode' => 'applibraryQrCode'，但实际类定义是class QRCode（大小写不一致）—— PHP 类名区分大小写，映射必须完全匹配 - 在控制器里用
new QrCode()成功，但用app()->make('QrCode')失败 —— 容器不认识这个映射，make()默认只查服务容器绑定，不走类库映射
正确做法：在 app/provider.php 同时完成路径注册 + 映射声明：
return [
'app\library\' => app_path('library'),
'QrCode' => 'app\library\QrCode',
];
遇到无命名空间的旧类库（如 CodeIgniter 风格工具类）怎么办
这类文件通常以 function xxx_helper() 形式存在，或用 class XXX {} 且无 namespace，TP6 默认拒绝加载——因为 PSR-4 加载器跳过无命名空间的文件。
只能手动引入，但必须控制时机和作用域：
- 不要在全局入口或配置文件里
require，避免每次请求都加载，浪费 I/O - 推荐在具体需要它的控制器方法内，用
include_once并加判断：if (!function_exists('some_old_helper')) { include_once app_path('library/old_helper.php'); } - 如果该类库含类定义（如
class OldUtil），需确认它没被重复定义，否则会报Cannot declare class - 这种类无法被
use或依赖注入，只能靠new OldUtil()或函数调用，属于兜底方案，不宜作为主力集成方式
Composer 类库和手动类库混用时的优先级陷阱
如果你同时用了 composer require 和手动放 app/library，TP6 加载器会按注册顺序查找：先找 vendor（Composer），再找 app/library（手动）。但一旦 Composer 包里有同名类（哪怕只是同名不同路径），就会永远命中 Composer 版本，手动类彻底失效。
典型场景：
- 你手动引入了
app/library/Cache.php，但项目又装了topthink/think-cache—— 框架永远加载后者，你的Cache类不会被触发 - 想覆盖某个 Composer 包里的工具类？别改
vendor，也别指望手动路径能“抢赢”，应该用服务容器绑定覆盖：app()->bind('thinkCache', pplibraryCache::class); - 检查冲突最简单的方式：在命令行运行
php think debug:autoload（需安装topthink/think-helper），看类名最终映射到哪个文件
手动类库不是补丁，是边界方案；真要长期用，优先走 Composer，或者把它封装成独立扩展包再 require。
