ThinkPHP模块自动加载未生效的根本原因是PSR-4映射缺失或命名不规范，而非框架不支持延迟加载；需确保目录结构合规、composer.json正确配置PSR-4、避免提前use/new、运行时按需加载配置与事件。
ThinkPHP 的模块自动加载为什么没生效
默认情况下 ThinkPHP 并不会“按需加载模块”，而是通过 APP_NAMESPACE 和 MODULES 配置一次性注册所有模块命名空间。所谓“延迟加载”其实是靠 PHP 的自动加载机制（__autoload / spl_autoload_register）在类首次被引用时才触发文件载入——但前提是模块的类名符合 PSR-4 规范，且自动加载器能正确映射路径。
常见错误现象：Class 'appordercontrollerOrder' not found，本质是自动加载器找不到该类对应的文件路径，不是框架没做延迟加载，而是映射关系缺失或命名不规范。
- 确保模块目录结构严格遵循
app/{module}/controller/、app/{module}/model/等约定 - 检查
composer.json中是否已为每个模块手动添加了 PSR-4 映射（如"app\order\": "app/order/"），否则composer dump-autoload不会识别新模块 - 不要依赖“运行时动态注册模块”来实现按需——ThinkPHP 6 的
App::bindModule()只影响路由解析，不修改自动加载逻辑
如何让 order 模块只在访问 /order 路由时才加载其类文件
这不是靠框架开关控制的，而是由 PHP 自动加载 + 路由调度共同决定的：只要没有代码主动 new、use 或反射调用 appordercontrollerOrder，它的文件就不会被加载。关键在于避免“提前引用”。
容易踩的坑：
立即学习“PHP免费学习笔记（深入）”；
- 在全局中间件或公共配置中
use appordermodelOrder—— 这会导致整个应用启动时就加载该类 - 在
app/common.php或服务提供者里实例化模块相关类 - 使用
Loader::import()手动引入，绕过了 PSR-4 自动加载的延迟特性
正确做法是：保持控制器、模型、服务类仅在对应请求生命周期内被路由或依赖注入触发，例如：
Route::get('order/list', 'order.controller.Order@list');
此时只有当该 URL 被访问，框架解析到 order.controller.Order 类名后，才会通过 Composer 自动加载器去定位并载入 app/order/controller/Order.php。
模块级配置和事件监听器怎么避免提前加载
模块自身的配置文件（如 app/order/config.php）和事件定义（app/order/event.php）默认会在应用初始化阶段被全部合并，这会破坏“按需”意图。它们不是类，不走自动加载，而是被 Config 和 Event 组件显式读取。
- 把模块专属配置移到运行时按条件加载：在控制器方法里用
config('order.api_url')前，先config(require __DIR__.'/config.php')，而不是放在全局配置合并流程中 - 事件监听器不要在
event.php里静态注册；改用Event::listen('order.created', [...])在业务逻辑中动态绑定 - 如果必须预注册，至少用闭包回调替代类字符串，避免类提前加载：
['app\order\service\OrderService', 'onPaySuccess']会触发类加载，而function() { (new OrderService)->onPaySuccess(); }不会
性能差异其实很小，别为模块数量焦虑
一个包含 5 个模块的 ThinkPHP 应用，即使全量注册命名空间，自动加载器也只是多存几条映射规则（数组键值对），并不会真的读取或编译任何模块 PHP 文件。真正影响性能的是文件 I/O 和 OPCache 命中率，不是“模块是否被声明”。
更值得关注的点：
- 确保
opcache.enable=1且opcache.file_cache开启，这对大量小模块文件尤其重要 - 避免在
app/provider.php中批量new各模块的服务类，这是真正的提前加载源头 - 模块间耦合导致的隐式加载（比如用户模块的模型里
use appordermodelOrder）比模块数量本身更伤性能
延迟加载机制本身是可靠的，但它的效果完全取决于你有没有无意中写下那行提前 use 或 new。
