入口文件 index.php 中 APP_PATH 路径写死或使用相对路径导致 500 错误，应统一用绝对路径定义；public 目录未设为 Web 根目录会导致路由失效；runtime 目录权限不足引发日志与缓存失败；数据库配置 hostname 用 localhost 可能导致连接超时，需改用 127.0.0.1。
入口文件 index.php 里 define('APP_PATH') 路径写死导致 500 错误
本地开发时习惯把 APP_PATH 写成 __DIR__ . '/../application/'，但服务器部署后如果项目不在 Web 根目录下（比如放在 /home/wwwroot/myapp/，而 Web 入口是 /home/wwwroot/myapp/public/），这个相对路径会错位，require 加载不到核心文件，直接报 PHP Fatal error 或空白页。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 统一用绝对路径定义
APP_PATH，例如：define('APP_PATH', dirname(__DIR__) . DS . 'application' . DS);（DS是 ThinkPHP 提供的目录分隔符常量，比硬写'/'更安全） - 检查
index.php中require的框架入口路径是否与服务器实际目录结构匹配，常见错误是漏掉thinkphp/start.php前的thinkphp/目录层级 - 上线前在服务器上执行
php -r "echo dirname(__DIR__);"确认当前脚本所在位置，再反推APP_PATH是否指向真实application目录
public 目录没设为 Web 服务器根目录，静态资源 404 或路由失效
ThinkPHP 5+ 强制要求 Web 服务器（Nginx/Apache）的根目录必须指向 public，否则 .htaccess 或 Nginx 的 try_files 规则不生效，所有 URL 都会绕过路由，直接返回 404 或暴露敏感文件。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- Nginx 配置中确认
root指向的是/path/to/your/project/public，不是项目根目录 - Apache 下确保
AllowOverride All已开启，且.htaccess文件未被服务器忽略（部分主机商会禁用mod_rewrite） - 测试方法：访问
http://yourdomain.com/index.php?s=index/index，能正常响应说明入口通；再访问http://yourdomain.com/，若返回首页说明伪静态已生效
application 和 runtime 目录权限不足，日志写入失败或缓存无法生成
服务器上 PHP 进程用户（如 www-data、nginx 或 apache）对 runtime 目录没有写权限，会导致 Cache、Log、Temp 子目录创建失败，报错类似 mkdir(): Permission denied 或 Failed to open stream: Permission denied。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 给
runtime目录赋 755（Linux）：chmod -R 755 runtime
，必要时改属组：chown -R :www-data runtime
- 不要给
application目录写权限（除非开发期需要自动生成配置），生产环境保持 644 即可 - 检查 SELinux 是否启用（CentOS/RHEL），临时关闭验证：
setenforce 0
；若问题消失，需用chcon重标上下文
数据库配置里的 hostname 用 localhost 导致连接超时
很多 Linux 服务器上，localhost 会让 MySQL 客户端走 Unix socket 连接，而生产环境数据库可能跑在 Docker、远程主机或开启了 TCP-only 模式，这时必须显式指定 127.0.0.1 才能走 TCP 协议。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 把数据库配置中的
'hostname' => 'localhost'改成'hostname' => '127.0.0.1' - 如果数据库在另一台机器，确认防火墙放行了 MySQL 端口（默认 3306），且 MySQL 用户授权允许远程连接（
GRANT ... ON *.* TO 'user'@'%'） - 用命令行快速验证：
mysql -h 127.0.0.1 -u your_user -p your_db
，能连上才说明 PHP 也能连
ThinkPHP 切换环境最常卡住的地方，往往不是代码逻辑，而是路径和权限这两层“看不见的依赖”——它们在本地因开发工具或集成环境自动兜底，一到服务器就立刻暴露。多花两分钟确认 APP_PATH 的实际解析结果、Web 根目录的真实路径、以及 PHP 进程对 runtime 的操作权限，比反复刷新 500 页面快得多。
