前言很多人在本地用 PhpStudy小皮面板学 Laravel 时第一步就卡住面板里新建了站点把 Laravel 压缩包解压到站点目录浏览器一打开看到的不是欢迎页而是下面几种东西之一——Nginx 的 404、Index of / 目录列表、public/index.php的源码原文或者一个 500 白屏。原因不复杂。Laravel 是单入口front controller框架所有请求都必须经过public/index.php这一个文件而新建站点时面板给出的默认根目录就是站点目录本身。只要站点根目录指向的不是public请求就永远到不了框架里。除此之外面板里还有四个东西会各自独立地把页面搞崩PHP 版本、PHP 扩展、URL 重写伪静态规则以及open_basedir路径限制。本文按建站 → 放代码 → 装依赖 → 配伪静态 → 跑起来的顺序把每一步会踩的坑讲清楚并给出一个可以直接在浏览器里跑的环境自检脚本。一、站点根目录必须指向 public不是项目根目录Laravel 的项目结构里public/是唯一允许被 Web 服务器直接暴露的目录里面通常只有index.php、robots.txt、favicon.ico和编译后的静态资源。项目根目录下的.env、storage/、vendor/、artisan都不应该能通过 URL 访问到——.env里放着数据库密码和APP_KEY一旦能被直接下载整个应用就等于对外公开了配置。在面板里新建站点时把网站根目录选到项目的public子目录站点域名: blog.test 网站根目录: D:/phpstudy_pro/WWW/laravel-blog/public PHP 版本: 8.2如果项目是网上下载的压缩包解压后往往还会多套一层目录例如laravel-blog-main/laravel-blog/public。根目录要指到最里层那个真正含index.php的public。指错一层症状就是 404 或目录列表。放代码之前先确认结构# 下面三个文件必须在同一层 ls public/index.php ls artisan ls composer.json二、PHP 版本和扩展先过 Laravel 的硬门槛Laravel 对 PHP 版本是硬性要求版本不够时 Composer 会在依赖解析阶段直接拒绝安装而不是装完再报错。Laravel 版本最低 PHP本地导入建议命令9.x8.0.2composer create-project laravel/laravel blog ^9.010.x8.1composer create-project laravel/laravel blog ^10.011.x8.2composer create-project laravel/laravel blog ^11.012.x8.2composer create-project laravel/laravel blog ^12.0扩展方面除了pdo_mysql下面这些是 Laravel 运行和 Composer 安装都需要的bcmath、ctype、curl、dom、fileinfo、json、mbstring、openssl、pcre、pdo、tokenizer、xml以及 Composer 解压依赖包时用的zip。如果站点能打开但页面报could not find driver就是pdo_mysql没开如果composer install报 requires ext-zip就是zip没开。这两个是最常见的。面板里勾选扩展后必须重启 PHP 服务光勾不重启是不生效的。三、伪静态让 index.php 接管所有 URLLaravel 的路由全部写在 PHP 里URL 里不出现.php后缀所以必须让 Web 服务器把不存在的路径统一交给index.php。PhpStudy 的面板里每个站点都有一个伪静态下拉框选laravel预设即可要手写的话Nginx 是这一句location / { try_files $uri $uri/ /index.php?$query_string; }Apache 侧不用自己写规则Laravel 自带的public/.htaccess已经包含了完整规则你要做的只是确保面板里该站点的AllowOverride是All否则 Apache 会忽略.htaccess表现为除了首页之外全部 404。验证方法很直接访问一个二级路由比如/login而不是只打开/。只测首页是测不出来伪静态有没有配好的。四、装依赖与配置 .env导入现成项目时vendor/目录通常不在压缩包里必须自己装cd /d D:/phpstudy_pro/WWW/laravel-blog # 1. 按 composer.lock 精确安装依赖 composer install # 2. 从模板生成配置文件Linux/macOS 用 cp .env.example .env copy .env.example .env # 3. 生成应用密钥 php artisan key:generate # 4. 建软链接让 storage/app/public 能被 URL 访问 php artisan storage:link # 5. 建表 php artisan migrate.env里对本地环境最有影响的几项APP_NAMEblog APP_ENVlocal APP_DEBUGtrue APP_URLhttp://blog.test DB_CONNECTIONmysql DB_HOST127.0.0.1 DB_PORT3306 DB_DATABASElaravel_blog DB_USERNAMEroot DB_PASSWORDrootAPP_KEY留空时任何需要加解密的请求都会 500报No application encryption key has been specified.。APP_DEBUGtrue只在本地开它会连带暴露数据库结构和配置项。注意DB_HOST用127.0.0.1而不是localhost。Windows 上localhost可能被解析成命名管道或走默认套接字和 TCP 走的不是同一条路会出现命令行mysql -u root -p能连PHP 连不上的迷惑现象。五、open_basedir 与目录权限500 的隐形杀手PhpStudy 会在站点级别注入open_basedir把 PHP 能访问的文件路径限制在指定目录内。Laravel 启动时要读上一级的.env、要往storage/logs/laravel.log写日志只要这些路径不在白名单里就会看到Warning: file_get_contents(): open_basedir restriction in effect. File(D:/phpstudy_pro/WWW/laravel-blog/.env) is not within the allowed path(s)处理办法有两个在站点设置里关掉防跨站攻击open_basedir或者把项目根目录追加进白名单。这是 Windows 本地环境里最常见的一类代码没错但就是跑不起来。Windows 下目录权限问题比 Linux 少但仍要保证storage/、storage/logs/、bootstrap/cache/可写否则缓存写不进去一样是 500。Linux 下# www 是 PHP-FPM 的运行用户以你的实际环境为准 chmod -R 775 storage bootstrap/cache chown -R www:www storage bootstrap/cache实战一个可直接在浏览器打开的环境自检脚本把下面这个文件存成public/env-check.php浏览器访问http://blog.test/env-check.php逐行看输出。检查完请删除它。?php declare(strict_types1); // public/env-check.php —— 临时自检脚本检查完务必删除 // 语法需要 PHP 7.4Laravel 11/12 本身要求 PHP 8.2 header(Content-Type: text/plain; charsetutf-8); echo PHP_VERSION : , PHP_VERSION, PHP_EOL; echo PHP_SAPI : , PHP_SAPI, PHP_EOL; echo loaded ini : , (php_ini_loaded_file() ?: (none)), PHP_EOL; echo memory_limit : , ini_get(memory_limit), PHP_EOL; $openBasedir ini_get(open_basedir); echo open_basedir : , ($openBasedir || $openBasedir false ? (off) : $openBasedir), PHP_EOL; echo PHP_EOL; // 项目根目录 public 的上一级 $root dirname(__DIR__); $sep DIRECTORY_SEPARATOR; echo 目录结构 , PHP_EOL; foreach ([public/index.php, artisan, composer.json, vendor/autoload.php, .env] as $rel) { $full $root . $sep . str_replace(/, $sep, $rel); echo $rel, : , (file_exists($full) ? OK : 缺失), PHP_EOL; } echo PHP_EOL, 可写性 , PHP_EOL; foreach ([storage, storage/logs, bootstrap/cache] as $rel) { $full $root . $sep . str_replace(/, $sep, $rel); echo $rel, : , (is_writable($full) ? 可写 : 不可写), PHP_EOL; } echo PHP_EOL, 扩展 , PHP_EOL; $required [ bcmath, ctype, curl, dom, fileinfo, json, mbstring, openssl, pcre, pdo, pdo_mysql, tokenizer, xml, zip, opcache, ]; foreach ($required as $ext) { echo $ext, : , (extension_loaded($ext) ? 已加载 : 未加载), PHP_EOL; } echo PHP_EOL, PHP 版本门槛 , PHP_EOL; $matrix [9.0 8.0.2, 10.0 8.1.0, 11.0 8.2.0, 12.0 8.2.0]; foreach ($matrix as $laravel $min) { echo Laravel , $laravel, 需要 PHP , $min, - , (version_compare(PHP_VERSION, $min, ) ? 满足 : 不满足), PHP_EOL; }命令行侧再跑一遍关键命令确认项目真的活起来了php artisan --version # 能看到 Laravel Framework 版本 php artisan route:list # 能看到路由表说明框架完整加载 php artisan migrate:status # 能看到迁移状态说明数据库通了常见坑点坑 1站点根目录指到项目根.env被公开下载❌ 网站根目录填D:/phpstudy_pro/WWW/laravel-blog✅ 网站根目录填D:/phpstudy_pro/WWW/laravel-blog/public浏览器里试一下http://blog.test/.env如果能下载到内容说明根目录一定指错了数据库密码已经泄露。坑 2DB_HOST写成localhost❌DB_HOSTlocalhost✅DB_HOST127.0.0.1坑 3面板切了 Web 的 PHP 版本命令行还是旧版本❌ 面板切到 8.2 后直接composer install报 requires php 8.2✅ 先用php -v确认真实版本再用绝对路径指定解释器D:/phpstudy_pro/Extensions/php/php8.2.9nts/php.exe \ D:/phpstudy_pro/Extensions/composer/composer.phar install坑 4伪静态没配只测了首页❌ 打开/看到欢迎页就以为配置完成✅ 访问/login这类二级路由确认try_files或AllowOverride真的生效坑 5open_basedir把项目根目录挡在外面❌ 白名单里只有站点根目录下的public✅ 关掉该站点的跨站攻击防护或把整个项目根目录加进白名单坑 6忘了php artisan key:generate❌copy .env.example .env之后直接访问页面✅ 先生成APP_KEY否则报No application encryption key has been specified.坑 7权限一刀切给 777❌chmod -R 777 .整个项目包括.env和vendor/✅ 只给真正需要写的目录chmod -R 775 storage bootstrap/cache总结步骤做什么做错了的症状建站根目录指向public404、目录列表、.env泄露选版本Laravel 11/12 需 PHP 8.2Composer 拒绝解析依赖开扩展pdo_mysql、fileinfo、zip等could not find driver、500配伪静态未匹配路径交给index.php除首页外全部 404装依赖composer installvendor/autoload.php缺失生成密钥php artisan key:generate500提示缺少APP_KEY放权限storage、bootstrap/cache可写500且日志写不进去本地导入 Laravel 卡住九成不是 Laravel 的问题而是站点根目录 PHP 版本 扩展这三件事里有一件没对上。先用自检脚本把环境事实打印出来再去看框架报错能省掉大量反复重启服务的无效操作。