ThinkPHP如何从零搭建完整项目 新手快速入门教程

新手跑通 ThinkPHP，别急着啃文档，先走完三步闭环：环境真实就绪、骨架一步生成、访问当场验证。很多人在“Class not found”“404”“白屏”这些地方卡住，说到底就是跳过了这几个基础检查。把这三步走稳了，才能真正上手学框架。

确认PHP和必需扩展已真实启用

只看 php -v 显示 8.2 可不够——关键是 php.ini 有没有真正生效、扩展有没有加载成功。

• 先跑 php --ini，看看 Loaded Configuration File 是不是指向你改过的那份 php.ini（别误认成 php.ini-development）
• 再执行 php -m | grep -E "mbstring|openssl|pdo|fileinfo"（Mac/Linux）或 php -m | findstr "mbstring openssl pdo fileinfo"（Windows），四项必须全部出现，缺一不可。
• 如果少了，去 php.ini 里找到对应 extension= 行，去掉前面的分号。Windows 下写 extension=fileinfo.dll，Linux/macOS 写 extension=fileinfo.so。
• 改完记得重启终端再验证——Windows 用户尤其容易忽略 PATH 还指向旧版 PHP 目录，改了也白改。

用 create-project 命令拉取完整骨架

千万别用 composer require topthink/think——那只是装了个代码包，不会生成项目目录结构，最后必然报 Class 'think\App' not found。

• 先用国内镜像提速：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
• 然后执行：composer create-project topthink/think blog，这会自动拉取最新的稳定版本并建好全套目录。
• 怕版本意外升级？加个版本号：composer create-project topthink/think blog 8.0.12，稳稳锁定。
• 完成后切进项目目录：cd blog，后面所有命令都在这里执行。

启动服务并验证首页是否真能打开

php think run 能执行，不等于页面能正常访问。关键点在于 public/ 目录有没有被正确识别为 Web 根目录。

• 在项目根目录下运行 php think run，看到 http://127.0.0.1:8000 的提示，说明服务已经启动。
• 浏览器打开那个地址，如果显示 “ThinkPHP V8.x” 欢迎页，才算真正成功。
• 如果遇到 404 或空白页，先检查三个地方：是否在项目根目录执行的命令、public/index.php 是否存在、.env 文件里 APP_DEBUG=true 有没有开启。
• 想要快速验证链路是否通？运行 php think make:controller Api/Hello，在生成的方法里返回 json(['msg'=>'OK'])，然后访问 http://127.0.0.1:8000/api/hello，看到 JSON 输出说明一切就绪。

常见问题一句话定位

遇到报错别慌，按这个顺序排查：

• 提示 Could not open input file think → 当前目录不是项目根目录，cd 进去再说。
• 页面空白或 500 → vendor/autoload.php 不存在或路径失效。如果移动过项目目录，记得重跑 composer dump-autoload 重新生成。
• 路由 404 → 执行 php think route:list 看看终端输出里有没有你注册的路由。光写个 URL 地址却没配对应的控制器方法，自然找不到。