1.3 环境搭建与目录结构

1.3 环境搭建与目录结构

版本选定了，本节把观察哨真正建起来：装 PHP、装 Composer、拉项目、跑服务器，然后沿目录逐站认路。这一节是全书唯一的纯动手章节，做完之后你的项目能响应请求，你的脑子里要装下这张目录地图——第 2 章讲请求生命周期时，每一个环节都会落到这里的某个目录上。

一、开工前的环境清单

ThinkPHP 8.x 对环境的要求集中在三点：PHP 版本不低于 8.0；开启常用扩展；装有 Composer。逐项检查：

# 看 PHP 版本，输出须为 8.0.0 及以上
php -v

# 看已启用扩展，重点确认下面几个在列
php -m
# 必需：pdo / pdo_mysql（数据库）、mbstring（多字节字符串）、
#       json、fileinfo（上传检测）、curl（网络请求）、gd（图片处理与验证码）

# 看 Composer 版本，2.x 为宜
composer -V
​

PHP 从哪来？Windows 开发机推荐直接用官方打包的 PHP 发行包解压后加入 PATH；macOS 可用 Homebrew 安装；Linux 服务器用发行版包管理器或编译安装。集成环境（宝塔、XAMPP 之类）也能用，但要确认它给的 PHP 版本可切换且扩展可勾选——框架对扩展的需求是硬性的，缺一个都会在安装或运行时以说不清的方式报错。

Composer 是 PHP 生态的依赖管理器，从 6.x 起 ThinkPHP 的框架本体与全部扩展都经它安装，没有它寸步难行。安装方式与校验步骤见 Composer 官方安装文档，装完在命令行里能执行 composer -V 即为成功。国内网络环境下建议把镜像源切到国内仓库，否则拉包可能慢到怀疑人生：

# 切换国内镜像源（阿里云）
composer config -g repos.packagist composer https://mirrors.aliyun.com/composer/
​

二、创建项目并跑通第一个请求

环境就绪后，用官方骨架创建项目。假设项目名叫 bookstore：

# 拉取官方骨架，最后一个参数是项目目录名
composer create-project topthink/think bookstore

cd bookstore

# 启动内置开发服务器，默认监听本机 8000 端口
php think run
​

看到启动提示后，浏览器访问本机的 8000 端口，出现 ThinkPHP 欢迎页即成功。这短短几行命令背后发生的事值得停下来看一眼：create-project 下载了骨架代码并执行了依赖安装；php think run 用的是框架自带的命令行入口——那个 think 文件就是第 8 章命令行工具的大门，现在先混个脸熟。

开发期用内置服务器足够；它默认只监听本机，要让局域网同事访问可加 --host 0.0.0.0 指定端口。生产环境不用它，走 Nginx 或 Apache，那是第 8 章部署一节的话题。

⚠️ 常见坑：第一次运行最常报的错是目录写权限——框架要在 runtime 目录里写缓存与日志，权限不给会直接白屏或抛异常。Linux/Mac 下给 runtime 目录写权限即可；Windows 下基本不会遇到。

三、目录结构：总线站台分布图

骨架建好，打开项目根目录。ThinkPHP 的目录约定相当稳定，认一遍受益全书：

bookstore/                  ← 项目根
├── app/                    ← 应用目录：你的业务代码几乎都住这里
│   ├── controller/         ← 控制器：接驳车司机
│   ├── model/              ← 模型：数据库专线
│   ├── service/            ←（约定俗成）业务服务层，自己建
│   ├── validate/           ←（约定俗成）验证器，自己建
│   ├── middleware/         ←（约定俗成）应用中间件，自己建
│   ├── view/               ← 模板文件
│   ├── event/  listener/   ← 事件与监听器
│   ├── exception/          ← 异常处理类
│   ├── common.php          ← 公共函数文件
│   ├── provider.php        ← 容器服务绑定
│   └──事件配置等
├── config/                 ← 全局配置：database.php、cache.php、route.php 等
├── route/                  ← 路由定义文件，app.php 为默认
├── public/                 ← Web 根目录：index.php 入口与静态资源，唯一对外暴露
├── runtime/                ← 运行时产物：缓存、日志，机器写机器读，别手改
├── vendor/                 ← Composer 依赖，别手改
├── .example.env            ← 环境变量样例，复制为 .env 使用
└── composer.json           ← 依赖清单
​

图 1-3：目录职责标注图

四、目录约定为什么值得较真

有人觉得目录结构是形式主义，随便放也能跑。技术上确实如此——PHP 加载类靠 Composer 的自动加载规则，只要命名空间对得上，文件放哪里框架都找得到。但约定乱掉的真实代价在三个月后：接手的人找不到类，你自己也找不到；自动加载优化、 IDE 跳转、第 8 章要讲的指令生成，全都依赖约定成立。框架社区形成的 controller/model/view/service 分层不是限制，是让「新人第一周就能干活」的社会契约。

两条实操建议：其一，service 与 validate 目录骨架里默认没有，是社区约定俗成的分层——业务逻辑别堆控制器，控制器只做「接收请求、调服务、返响应」三件事，这段纪律到第 2 章讲 MVC 时还会加强。其二，.env 文件存数据库密码等敏感配置，务必加入版本控制忽略名单，仓库里只提交 .example.env 样板——这个习惯会在第 8 章环境管理一节继续展开。

五、排错速查：装不上、跑不起来的常见原因

按出现频率排：PHP 版本不足，报错关键词是语法不认识或特性不存在，php -v 一查便知，换版本解决；扩展缺失，典型如缺 pdo_mysql 时数据库配置一测就断，php -m 对照第一节的清单补齐；Composer 拉包超时，切国内镜像后重试；端口被占，php think run -p 8080 换端口；欢迎页能开但访问应用报 404，检查访问的 URL 与路由定义是否匹配，第 3 章会系统讲路由，现阶段先确认控制器文件名与类名大小写完全一致。

本节要点回顾

• 环境三件套：PHP 8 及以上、常用扩展齐全、Composer 可用，缺一项都会以隐晦报错的形式拦路。
• 两条命令建站：composer create-project topthink/think 项目名 拉骨架，php think run 起开发服务器。
• 目录即地图：public 是唯一大门，app 住业务，config 与 route 立规矩，runtime 与 vendor 只读不摸。
• 约定有回报：遵循 controller/model/service 分层，换来的是自动加载、IDE 支持与团队协作的全部红利。
• 排错有序：版本、扩展、镜像、端口、路由五类问题覆盖了新手期绝大多数安装故障。

总线已铺好、站台已命名。下一章正式发车：看一个请求如何穿过第 2 章的总线主干——生命周期、容器与中间件。