本地环境搭了八遍才跑通项目：写给刚摸ThinkPHP的新手，关于目录该放哪、入口怎么找、调试怎么省时间

上周帮朋友看一个他"从网上下的教程源码"，解压完直接双击public里的index.php，结果浏览器白屏，他以为代码坏了，差点重装系统。我远程过去一看，PHP版本5.6，ThinkPHP6要求7.2+，.env文件里数据库密码还是教程作者的本地密码。这场景太熟悉了，三年前我也这样。

所以干脆整理下，给刚入门的同学画个重点：拿到一个TP项目，别急着跑，先认门。

一、目录不是随便摆的，认清楚再动

很多人解压完看到一堆文件夹就懵。核心就记这几个：

app/ —— 你的业务代码全在这，控制器、模型、中间件按模块分。新手常犯的错误是往根目录丢自己的PHP文件，结果命名空间对不上，autoload找不到类。

config/ —— 数据库、缓存、路由配置。本地调试第一件事：复制.example.env成.env，改里面的DB_HOST为127.0.0.1，别写localhost（某些环境下解析慢到怀疑人生）。

public/ —— 唯一该指向Web服务器的目录。nginx或Apache的root必须设到这，不是项目根目录。我见过太多人根目录指向了整个项目，然后/app/controller直接能访问到，源码裸奔。

runtime/ —— 缓存、日志、编译文件。本地开发时权限问题高发区，Linux下给777最省事，生产环境另说。

vendor/ —— composer依赖，别手动改里面的东西，改完下次composer update全白费。

二、入口文件到底在哪，怎么配

ThinkPHP6的入口很干净，就一个public/index.php。但"入口"不只是这个文件，是整个请求怎么流进来的。

本地用phpStudy或小皮面板的同学，新建站点时网站目录选到public，不是上级文件夹。然后伪静态规则选thinkphp，自动生成：

location / {
    if (!-e $request_filename){
        rewrite  ^(.*)$  /index.php?s=$1  last;   break;
    }
}

没配伪静态的话，路由美化全失效，你只能访问/index.php/admin/index/login这种丑地址，而且参数传法也变了。

如果你用PHP内置服务器测试（比如临时看下效果），命令行进项目根目录执行：

php think run

这会自动把public当根目录起服务，端口默认8000。比你自己瞎配Apache省十分钟。

三、本地调试我现在的习惯

以前我改个控制器要FTP上传看效果，现在坚决本地闭环。推荐组合：

• PHPStorm + Xdebug：断点调试是真香，尤其是链式操作报错时，能逐行跟到具体哪一步返回了null。装Xdebug别下错版本，用官方的那个wizard.php，贴phpinfo全文进去，它告诉你下哪个DLL、放哪、php.ini加什么。

• 开启调试模式：项目根目录.env里加APP_DEBUG = true，报错页面会显示调用栈、SQL语句、请求参数。但上线前务必改false，否则数据库账号密码可能跟着报错信息一起漏出来。

• 日志级别调低：config/log.php里把level从error改成info，开发阶段SQL执行记录、缓存命中情况都能看见。上线再切回去，不然runtime/log文件夹几天就撑爆。

四、一个我踩过的具体坑

有次从GitHub拉了个开源商城，本地跑起来首页正常，一点分类就500错误。调试模式一开，提示Driver [Think] not found。翻半天发现作者用了think-template引擎，但composer.json里没写这个依赖，他本地是全局装的。我执行composer require topthink/think-template解决。这种"作者环境和你不一样"的问题，新手能卡一晚上。

所以我的建议：拿到陌生项目，先composer install，再看README有没有特殊扩展要求，最后检查.env和数据库导入。三步做完再点浏览器，少生很多气。

五、最后说两句

刚开始我也觉得这些"基础"很枯燥，想直接写功能。直到有次把测试环境的DB_DATABASE配成生产库，一条migrate把用户表清空了，才痛定思痛。现在每个新项目，我先花二十分钟把目录结构、环境配置、调试工具理顺，后面省下的时间远不止这些。

你们本地环境第一次跑通TP花了多久？有没有被什么奇葩配置坑过？