ThinkPHP 8 并非下载即用的框架，而是一个依赖于协同工作环境的高性能 PHP 框架。其运行核心包含三大要素：具备特定扩展的 PHP 环境、Web 服务器（推荐 Apache 或 Nginx）以及 PHP 依赖管理工具 Composer。环境缺失或配置不当，将导致页面 404、登录失败或数据库操作报错等常见问题。
必须安装的三项基础软件
以下三项为必须安装的硬性要求，缺一不可：
- PHP 8.0.0 或更高版本：ThinkPHP 8 强制要求 PHP 8.0.0 及以上版本，版本过低将直接导致
composer create-project中断。建议通过php -v命令确认版本，而非仅依赖 XAMPP 控制面板显示。 - 四个关键 PHP 扩展必须开启：必须开启 mbstring、openssl、pdo_mysql（或 pdo_sqlite）和 fileinfo 四大扩展，否则数据迁移、加密、数据库连接和文件上传功能将无法使用。可通过
php -m | grep -E 'mbstring|openssl|pdo|fileinfo'检查，若未输出，则需在 php.ini 中取消对应extension=行前的注释。 - Composer 2.0+：Composer 2.0 及以上版本用于生成完整的可运行项目，而非仅安装 ThinkPHP 库。请勿使用
composer require topthink/think，否则将缺少 public 入口、app 目录等核心文件，导致Class 'thinkApp' not found错误。
Web服务器配置是成败关键
ThinkPHP 6+ 采用单入口架构，Web 服务器根目录必须指向 public/ 子目录，而非项目根目录。此配置错误是 90% 新手遇到白屏或 404 错误的根源。
- Apache 用户：确认已启用 mod_rewrite 模块（检查 httpd.conf 中
LoadModule rewrite_module前无 #），并在虚拟主机或目录配置中设置AllowOverride All，以确保 .htaccess 文件生效，避免路由（如/admin/login）返回 404。 - Nginx 用户：在 server 块中，确保 root 指向
/path/to/your/project/public，并添加关键规则try_files $uri $uri/ /index.php?s=$uri&$args;。缺少s=$uri&$args将导致 POST 数据丢失，登录表单提交后无响应。 - XAMPP/WAMP 用户：不要直接将整个项目放在 htdocs 目录下。应修改 Apache 的 DocumentRoot 指向项目内的 public 目录，或配置虚拟主机（推荐）。例如，设置
ServerName tp8.test，并在系统 hosts 文件中添加127.0.0.1 tp8.test。
初始化项目不能跳过的三步操作
仅有文件结构不足以运行项目，数据库和用户账户需要手动创建与激活：
- 在项目根目录执行：
php think migrate:run—— 创建 users 表等数据表结构。若未执行此步骤，登录时将持续提示“用户名或密码错误”。 - 接着执行：
php think seed:run—— 插入默认管理员账号（通常为 admin/admin）。跳过此步骤会导致数据表为空，任何登录尝试都将失败。 - 检查 .env 文件是否存在且未被错误重命名（如 .env.txt）。数据库连接、调试开关等配置默认为注释状态，需手动取消注释并填写正确信息。直接修改 config/database.php 文件是无效的。
权限与安全细节别忽略
开发环境运行正常不代表配置已经完善，以下细节同样关键：
- runtime 目录必须可写：日志、缓存、模板编译均依赖 runtime 目录。Linux 环境下，可使用
chmod -R 755 runtime设置权限；Windows 环境下，需右键属性 → 安全，为 Web 服务用户（如 IIS_IUSRS 或 www-data）添加写入权限。 - 禁用危险函数（生产环境必需）：在 php.ini 中添加
disable_functions = exec,passthru,shell_exec,system,proc_open,popen，以防止命令注入攻击。 - 登录控制器加限流中间件：打开 app/controller/LoginController.php，将
$this->middleware = [];修改为$this->middleware = ['throttle:5,1'];，以防范暴力破解攻击。
