本地环境搭了八遍才明白：目录结构不是"随便放"，入口文件也不是"双击就能跑"

上周帮一个朋友看项目，他解压完源码直接双击 public/index.php，然后截图问我为什么浏览器显示的是代码本身。我愣了三秒，突然意识到——当年我也是这么过来的。

今天不聊高深的东西，就说说新手最容易栽的三个"基础坑"。这些坑我全踩过，而且每个都至少浪费了我一个下午。

一、目录结构：别被"看起来整齐"骗了

很多新手喜欢把项目文件摊平，或者按"自己觉得顺眼"的方式重组。我见过最离谱的，是把 vendor 重命名为 第三方包，因为"英文看着不舒服"。结果 Composer 更新时直接原地爆炸。

ThinkPHP6 的目录设计是有讲究的。app 放业务，config 放配置，route 放路由——这些都没问题。但关键是 public 这个目录，它必须是唯一对外暴露的入口。你的 Nginx/Apache 配置里，root 指向的必须是 public，而不是项目根目录。

我早期犯过一个错：为了图方便，把上传目录 uploads 放在了 app 同级，然后写了个软链到 public。本地测试没问题，搬到线上发现某些主机商禁止跨目录软链，图片全裂。后来老老实实改成 public/storage，用符号链接或者路由重写解决，反而更干净。

二、入口文件：它不只是"一个 PHP 文件"

public/index.php 里面就几行代码，但每一行都在干活。最上面定义 APP_PATH，中间加载自动加载器，最后启动应用。很多新手一看"这么简单"，就忍不住动手改——比如把调试开关硬编码进去，或者加个自己写的"全局函数文件"引用。

我的建议是：入口文件保持原样，需要全局加载的东西放到 provider.php 或者自定义服务里。我曾在入口文件里加了一段 header('Access-Control-Allow-Origin: *') 来解决跨域，结果上线后安全扫描直接标红。后来改成中间件处理，按需配置，才算正规。

还有个细节：本地用 PHP 内置服务器启动时，命令是 php think run，它会自动把 public 作为文档根目录。但如果你手动用 php -S localhost:8000，默认根目录是当前执行位置，这时候访问 /index.php 和 /public/index.php 完全是两回事。我因为这个，曾经调试了两个小时为什么路由全部 404。

三、本地调试环境：别用生产配置"将就"

新手最容易复制线上 .env 到本地，然后改几个数据库参数就完事。但有几个配置项，本地和生产应该是相反的：

APP_DEBUG 本地开 true，线上必须 false——这个大家都知道。但 APP_TRACE 呢？很多人没注意，开着 trace 上线，页面底部直接暴露 SQL 语句和文件路径，等于给攻击者送地图。

还有数据库的 DEBUG 模式，ThinkPHP6 里如果开了，会记录每一条 SQL 到日志。本地无所谓，线上高并发时磁盘能被日志打满。我有一次忘了关，三天后服务器报警，/var/log 占了 80% 空间。

本地环境我现在的习惯是：单独维护一个 .env.local，用 phpdotenv 的覆盖机制加载。Git 里忽略掉，团队成员各自保留自己的本地配置。这样不会有人"不小心把调试模式推到线上"。

最后说个真事

去年我重装系统后急着跑项目，顺手把源码扔进了带中文路径的文件夹。Composer install 没问题，运行时报错 "failed to open stream"，路径里一堆乱码。排查了四十分钟，才想起 Windows 下 PHP 对中文路径的支持有多脆弱。现在我的项目全在 D:/dev/ 下，目录名只用英文和小横线，再没出过这种玄学问题。

这些坑没什么技术含量，但新手期被它们绊住，挫败感极强。写出来算是给曾经的自己提个醒，也希望能帮刚入门的朋友少熬几个夜。

你们本地环境搭的时候，有没有遇到过什么"看起来弱智但卡了很久"的问题？