如何配置ThinkPHP多应用模式及模块化多应用开发方案？

本文共计976个文字，预计阅读时间需要4分钟。

ThinkPHP多应用模式并非仅靠更改配置就能启动，必须同时满足目录结构、命名空间、路由导入和自动加载四个方面条件，缺一不可。

app 目录下没建对子目录，AppNotFoundException 就会直接报给你看

框架不会自动创建 app/admin 或 app/api 这类目录——你得手动建，或用命令行工具生成。否则即使配置全开，请求进来也找不到控制器。

• 执行 php think app:create admin（TP6.1+）或 php think build admin（旧版），确保 app/admin/ 下有 controller/、model/、view/、config/ 等标准子目录
• 模块名必须是合法 PHP 类名：只含字母、数字、下划线，且不能以数字开头；admin 可以，1admin 或 user-api 会失败
• 删掉原始的 app/controller 目录——这是单应用标志，不删会导致框架误判为单应用模式

config/app.php 里只设 'app_multi_module' => true 不够

这个配置只是“允许多模块”，但真正启用多应用识别，还得靠 'auto_multi_app' => true 和 'app_namespace' => 'app' 配合。否则类自动加载会失败，报 Class not found。

• 确认已添加：'auto_multi_app' => true、'app_namespace' => 'app'、'default_app' => 'index'
• 如果用的是 topthink/think-multi-app 扩展（推荐），还要检查 config/app.php 的 'providers' 数组是否包含 \think\multi\AppServiceProvider::class
• 修改完配置后，务必清空 runtime/cache/ 和 runtime/route/，否则旧路由缓存会掩盖配置生效情况

子应用路由不显式 Route::import()，就是死文件

config/route.php 是全局入口，但它不会自动扫描 app/*/route.php。每个子应用的路由必须手动导入，否则 URL 匹配不到任何控制器。

立即学习“PHP免费学习笔记（深入）”；

• 在 config/route.php 中写：Route::import('admin', 'admin') —— 第二个参数是子应用目录名，大小写敏感，必须和 app/admin 完全一致
• app/admin/route/app.php 里不要再套 Route::group('admin', ...)，否则访问路径变成 /admin/admin/login
• 新增应用后，必须同步追加对应的 Route::import() 行，漏一条，那个应用就完全不可达

域名绑定要配 domain_bind，但别忘了入口文件和 Web 服务器重写

仅在 config/app.php 写 'domain_bind' => ['admin.example.com' => 'admin'] 不足以让 admin.example.com 正常工作。

• 需要为每个域名准备独立入口文件，比如 public/admin.php，内容与 index.php 几乎一致，只改一行：define('APP_NAME', 'admin')
• Web 服务器（Nginx/Apache）必须把该域名请求指向对应入口文件，例如 Nginx 的 root 指向 public/，再用 fastcgi_param SCRIPT_FILENAME $document_root/admin.php;
• 若走 public/index.php 统一入口，域名绑定依赖 PATH_INFO 解析，此时需确保 app.url_common 为 true，否则无法从 Host 头提取应用名

最易忽略的一点：多应用之间默认不共享模型、中间件和配置。想复用用户模型？得放到 app/common/model/ 并用完整命名空间引用；想给 admin 应用单独配 Redis 缓存前缀？得在 app/admin/config/cache.php 里覆盖 'prefix'，而不是改全局配置。