ThinkPHP部署成功的关键是public目录设为Web根、runtime目录可写、Nginx正确转发请求至index.php；三者对齐可解决80%的404、空白页、Class not found、502等报错。
ThinkPHP部署到服务器不是“上传完就能跑”，新手最容易卡在三处：public目录没设成Web根、runtime目录不可写、Nginx没把请求正确交给index.php。只要这三点对齐，80%的报错（404、空白页、Class not found、502）当场消失。
一、确认PHP环境和必需扩展
别只看php -v，要验证实际运行环境是否匹配框架要求：
- TP6.1+ 要求 PHP ≥ 7.4，TP8 强制要求 PHP ≥ 8.0.0；终端执行 php -v 和 /usr/bin/php-fpm81 -v（路径按实际查）必须一致且达标
- 缺一个扩展就可能崩：运行 php -m | grep -E "mbstring|openssl|pdo_mysql|fileinfo|curl"，确保全部出现；Ubuntu/Debian 上 pdo_mysql 常需额外安装 php-mysql
- 启用 opcache：编辑 /etc/php/*/fpm/php.ini，设 opcache.enable=1 和 opcache.validate_timestamps=0；别忘了加 opcache.enable_cli=1，否则 php think 命令会失败
- memory_limit 建议调至 256M 或更高，避免大日志或调试时静默崩溃
二、代码放对位置，public必须是Web根目录
这是最常被跳过的硬前提。ThinkPHP 是单入口框架，所有请求必须经 public/index.php 分发：
- 把整个项目上传后，Nginx 的 root 必须指向 /your/project/path/public，绝不能指到项目根目录（如 /var/www/myapp）
- 若 root 错设为项目根目录，会导致 app/、config/ 目录直接暴露，存在源码泄露风险；同时 index.php 找不到 vendor/autoload.php，报 Class 'think\App' not found
- 宝塔面板用户：新建站点后，在「网站设置 → 根目录」里手动改为 public 子目录
- 检查 Nginx 用户（如 www-data 或 nginx）对 public 及其上级目录有可执行（x）权限，否则无法遍历路径
三、Nginx配置要干净、精准
配置错一个字符，就会 404 或下载 index.php 源码。关键不是“支持 ThinkPHP”，而是转发逻辑无歧义：
立即学习“PHP免费学习笔记（深入）”；
- location / 块用最稳写法：try_files $uri $uri/ /index.php?$query_string; —— 先找真实文件，再找目录，最后交由 index.php 处理并透传全部参数
- 删掉或注释掉所有 fastcgi_split_path_info 相关行；TP8 默认走 querystring 模式，不需要 PATH_INFO
- SCRIPT_FILENAME 必须用 $realpath_root$fastcgi_script_name，不用 $document_root，避免软链接部署时路径解析失败
- fastcgi_pass 要与 PHP-FPM 实际监听方式严格匹配：Unix socket 写 unix:/run/php/php8.1-fpm.sock，TCP 写 127.0.0.1:9000（别用 localhost）
四、runtime权限和环境配置不能跳
页面空白或 500，大概率卡在这几步：
- 查 Nginx 工作进程用户：ps aux | grep nginx | head -1（Ubuntu 多为 www-data，CentOS 多为 nginx）
- 查 PHP-FPM 配置里的 user/group：/etc/php/*/fpm/pool.d/www.conf，必须和 Nginx 用户一致或同组
- 执行：chgrp www-data runtime && chmod 775 runtime && chmod g+s runtime —— g+s 确保新生成的子目录自动继承组权限
- .env 文件必须放在项目根目录（和 think 命令同级），内容如 DB_HOST='127.0.0.1'、APP_DEBUG=false；敏感密码含 @ ! 等特殊字符时，务必用单引号包裹：DB_PASSWORD='p@ss!word'
- 生产环境禁用 APP_ENV 在 fastcgi_param 或系统环境变量中预设，否则 .env 完全不加载
五、vendor和runtime要重新生成，别直接复制
本地 vendor 目录不能直接上传，原因很实在：
- 本地和服务器 PHP 版本、扩展不同，autoload_classmap.php 等缓存文件不兼容
- 开发依赖（phpunit、faker）不该进生产环境
- Git 部署时 vendor 通常被 .gitignore 排除，上传后为空
- 上传前删掉本地 vendor/ 和 runtime/ 目录；上传 composer.json 和 composer.lock 后，在项目根目录执行：composer install --no-dev --optimize-autoloader
- 确认执行后 vendor/autoload.php 存在且可读，再检查 php -i | grep opcache 输出非空
