一、问题/场景描述
许多开发者在本地Windows或Mac环境下使用ThinkPHP框架进行开发时，项目运行一切正常。然而，当将代码部署到Linux生产服务器后，访问应用却出现了404 Not Found错误。这种“本地正常，线上404”的典型问题，通常与服务器环境和配置差异有关，需要进行系统性的排查。
二、原因分析
造成此问题的原因多样，核心在于本地开发环境与线上服务器环境的差异。最常见的原因包括：服务器未正确配置URL重写（导致路由失效）、项目入口文件路径不正确、运行目录或权限设置错误、以及ThinkPHP的伪静态规则未生效。此外，服务器PHP扩展缺失或版本不匹配、.htaccess或Nginx配置不当，也可能导致框架的核心调度器无法正常工作，从而将所有请求都返回404状态。
三、详细解决步骤
请按照以下步骤，由简到繁进行排查。
步骤1：检查基础访问与入口文件
首先，直接访问项目的入口文件（通常是 public/index.php），以确认PHP和基础文件是否能正常执行。
# 在服务器上使用curl测试入口文件
curl -I http://你的域名或IP/public/index.php
如果返回200状态码，说明入口文件可访问，问题可能出在路由或重写规则上。如果也是404，则需检查文件是否真实上传，路径是否正确。
步骤2：配置URL重写（伪静态）
ThinkPHP依赖URL重写来实现优雅路由。根据你的Web服务器进行配置。
对于Nginx服务器： 检查站点配置文件，确保包含了对ThinkPHP的支持规则。
location / {
if (!-e $request_filename){
rewrite ^(.*)$ /index.php?s=$1 last; break;
}
}
# 或者ThinkPHP 6.x+ 推荐的配置
location / {
try_files $uri $uri/ /index.php?s=$uri&$args;
}
修改配置后，务必重载Nginx。
sudo nginx -s reload
对于Apache服务器： 确保public目录下的.htaccess文件已上传，且Apache开启了mod_rewrite模块。
步骤3：检查运行目录与权限
确保Web服务器（如www-data或nginx用户）对项目目录，尤其是runtime目录有读写权限。
# 进入项目根目录，通常需要给runtime目录设置写权限
chmod -R 755 runtime
# 或者更改所属用户组（根据你的实际Web用户调整）
chown -R www-data:www-data /path/to/your/project
同时，在宝塔面板或cPanel等环境中，需确认网站的运行目录是否正确指向了项目的public目录，而不是根目录。
步骤4：调试ThinkPHP路由与配置
在项目配置文件config/app.php中，临时开启调试模式，可能看到更详细的错误信息。
// config/app.php
return [
'app_debug' => true, // 设置为true
// ...
];
此外，检查路由配置config/route.php，确保没有错误的规则导致拦截。可以尝试先注释掉所有自定义路由，测试基础路由是否工作。
步骤5：验证PHP环境与扩展
通过创建一个phpinfo.php文件来确认服务器PHP版本和扩展是否满足ThinkPHP要求，特别是mbstring, openssl, pdo等。
echo "" > /path/to/public/phpinfo.php
访问这个文件进行确认后，请务必删除它。
四、注意事项
排查时建议遵循先易后难的原则，从服务器配置（重写、权限）到应用配置（调试模式、路由）逐步深入。修改服务器配置前做好备份。开启app_debug模式仅用于临时排查，生产环境务必关闭。确保本地与服务器使用的ThinkPHP核心版本一致，避免因版本差异导致兼容性问题。
五、适用环境
本排查指南适用于将ThinkPHP项目从本地开发环境部署到线上Linux服务器（如CentOS、Ubuntu）时遇到的404问题。