ThinkPHP环境搭建所需配置一站式教程

搭建ThinkPHP服务器环境，核心需要三要素：PHP 8.0（请注意，严格避免使用8.3及以上版本）、Web服务器（Nginx或Apache）以及Composer。三者缺一不可，且安装顺序有严格讲究——首先安装PHP并启用关键扩展，然后配置Web服务器指向public目录，最后通过Composer初始化项目。不要以为装好就能正常运行，版本不对、目录设置错误、规则配置有误，轻则出现白屏404，重则遇到502错误，排查起来相当耗时。

PHP 8.0必须安装这5个关键扩展

ThinkPHP 6和8对PHP版本及扩展有严格限制，这一点不能马虎：

• 必须使用PHP 8.0，而非最新的8.3或8.4版本。在宝塔面板的软件商店中手动选择安装，务必注意不要选错；
• 安装完成后，进入PHP设置 → 扩展管理，勾选并启用以下扩展：fileinfo、openssl、mbstring、pdo_mysql、redis；
• 扩展安装后务必点击「重启PHP服务」，否则扩展不会生效；
• 若在Windows本地部署，需编辑php.ini文件，去掉这5行前的分号，然后在命令行中运行php -m | findstr "mbstring openssl"，确认能看到相关扩展输出；
• CLI命令行的PHP版本需与Web端保持一致。执行where php（Windows）或which php（Linux/macOS）检查路径，避免终端调用旧版PHP导致调试时发现问题。

Web服务器必须指向/public目录

ThinkPHP采用单入口设计，唯一入口index.php位于public/目录下。如果根目录设置错误，不仅会导致.env和config/暴露在外，还会使所有路由失效。具体配置方法如下：

• 宝塔面板：添加站点后，进入「设置」→「网站目录」，运行目录填写 /public（注意开头带斜杠），然后勾选「重载Nginx配置」；
• Nginx伪静态规则：在站点设置的伪静态配置中粘贴标准写法：
  location / { try_files $uri $uri/ /index.php?$query_string; }
• 若使用Apache，需确保DocumentRoot指向/path/to/project/public，且对应的块中已启用AllowOverride All；
• 本地开发可采用快捷方式：直接运行php think run，它将自动启动内置服务器；或者使用php -S localhost:8000 -t public/，注意-t public/参数绝对不能遗漏。

使用create-project初始化项目，避免使用require

有些开发者图方便直接执行composer require topthink/think，结果仅下载了核心类库，缺少public、app、think脚本及路由系统，最终导致Class 'thinkApp' not found错误或404页面。正确步骤如下：

• 新建一个纯英文、不含空格和中文的空文件夹（例如D:\tp8）；
• 进入该目录，运行命令：composer create-project topthink/think .（末尾的点表示当前目录，切勿遗漏）；
• 如需指定版本，可添加@8.0后缀：composer create-project topthink/think tp8@8.0；
• 项目生成后，think文件位于根目录。在Linux/macOS系统中需赋予执行权限：chmod +x think；
• 首次运行前，删除runtime/缓存目录，并检查.env文件中的APP_DEBUG=true是否已取消注释。否则错误信息将被隐藏，只会显示白屏，排查过程非常困难。

让.env配置生效的关键细节

.env文件的优先级高于PHP配置文件，但许多人在修改后忘记清理缓存、重启进程，导致修改无效：

• .env文件必须放置在项目根目录（与think脚本同级），而非public/或app/目录下；
• 数据库配置使用扁平格式：例如DB_HOST=127.0.0.1、DB_NAME=tp8，不要写成database.host等嵌套形式；
• 修改后务必清空runtime/cache/目录（最彻底的做法是直接删除整个runtime文件夹）；
• 若使用php think run，按Ctrl+C停止后重新运行；若使用PHP-FPM，执行sudo systemctl reload php-fpm；
• 在国内网络环境下，建议配置阿里云镜像，可显著提升下载速度：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/。