ThinkPHP新手第一课：解决public/index.php访问空白与路由404报错【教程】

先说个新手经常遇到的场景：刚装好ThinkPHP，打开public/index.php，一片空白。访问/user/list，直接404。你盯着屏幕看了半天，代码一行没写错，可页面就是不干活。这事儿，其实大概率不是代码的问题，而是框架压根没跑起来——据统计，90%的新手卡在这一步：入口文件没被PHP执行，或者请求根本没进到路由系统里。

确认PHP环境和扩展是否就绪

先别急着改代码。在终端里敲个php -v，确认版本≥8.0（TP8）或≥7.2（TP6）。再跑一句php -m | grep -E 'mbstring|openssl|pdo|curl'，这四种扩展的输出必须一个不少。缺少任意一个，public/index.php就会直接500或白屏，而且很可能连个报错信息都不给你。

Windows用户特别留意：XAMPP自带的PHP版本通常偏旧，默认还禁用了PDO。Mac用Homebrew装PHP的，经常漏掉openssl，得手动补一句brew install php@8.2-opcache然后再重装。

验证think命令能否在项目根目录运行

下一步，确认你所在的位置。cd进入包含think、app/、public/、vendor/这四个东西的最外层目录——不是public，也不是app，是整个项目文件夹。

接着执行php think build。TP8新装后，这一步绝对不能跳过，否则app/目录是空的，控制器压根不存在。

如果报错“Could not open input file think”，说明你没在根目录下。如果报“Class "thinkConsole" not found”，检查一下think文件的首行：Linux/macOS必须保留#!/usr/bin/env php这行，Windows下必须删掉它，否则PHP解释器直接跳过后面所有内容。

排查public/index.php空白原因

浏览器里敲下http://localhost/your-project/public/index.php，空白或500。这不是路由的问题，是Web服务器没把请求交给PHP处理。

先用curl验证一下：curl -I http://localhost/your-project/public/index.php。响应头里如果有X-Powered-By: ThinkPHP，说明PHP已经跑起来了。如果只看到Server: nginx或Server: Apache，那问题就出在Web服务器的配置上。

Apache用户留个心眼：检查public/.htaccess是否存在，并且虚拟主机配置里AllowOverride All是否已打开。Nginx用户则要确认server块里有没有这行：location / { try_files $uri $uri/ /index.php?$query_string; }——少了$query_string，GET参数就会丢失，后续路由匹配自然失败。

宝塔用户最容易踩坑：进入【网站】→【设置】→【网站目录】→【运行目录】，必须选/public（注意开头带斜杠）。改完点【保存】，再【重启】站点，否则配置不生效。

解决路由404的核心操作

方法一：用命令行验证路由是否真的被加载。
执行php think route:list，如果列表是空的，或者没有你写的/user/list，说明路由文件压根没执行。这时可以在route/app.php第一行加一句die('route loaded');，刷新页面看是否中断——不中断，就说明该文件没被加载。

方法二：确认路由定义位置与模式匹配。
TP6默认读取route/app.php。TP8多应用模式下，app/route/app.php只对名为app的应用生效。如果想全局生效，要么改用app/route.php，要么在public/index.php中调用App::useAppMulti(false)关闭多应用。

方法三：检查Web服务器伪静态是否生效。
如果/user/list返回404，但/index.php/user/list能正常访问，那就说明伪静态没生效。Nginx必须使用try_files $uri $uri/ /index.php?$query_string;，不要再用过时的rewrite ^(.*)$ /index.php?s=$1 last;，TP6和TP8默认已经不认s=参数模式了。

方法四：强制路由可能导致静态资源404。
如果config/app.php中'url_route_must' => true已开启，所有请求（包括/static/logo.png）都会走路由匹配。这时候需要在route/app.php顶部加一条放行规则：Route::rule(':path^.*.(js|css|png|jpg|gif|svg|woff2|ttf)$', 'static/:path', 'GET', ['ext' => '']);。注意，['ext' => '']这句不能少，否则/a.js会被自动补上.html后缀，导致匹配失败。