小皮面板部署 Laravel 项目需要注意什么？

学完这篇，你能在小皮面板上把 Laravel 项目从上传到访问正常跑起来，并避开运行目录、伪静态、PHP 扩展和权限这几类常见坑。

第一步：确认 PHP 版本并装齐扩展

这一步要选对 PHP 版本并开启 Laravel 必需扩展，做完后环境才满足框架要求。进入小皮面板左侧「软件商店」->「运行环境」，安装 Nginx 1.24、MySQL 8.0、PHP 8.2。Laravel 11 需要 PHP 8.2+，Laravel 10 需要 PHP 8.1+，Laravel 9 需要 PHP 8.0+，别用 PHP 7.4 硬跑新版本。再到「网站」->「PHP设置」->「扩展」，勾选 fileinfo、openssl、pdo_mysql、mbstring、tokenizer、xml、ctype、json、bcmath、curl、gd、zip；用 Redis 就再开 redis。

注意：小皮面板默认可能禁用 putenv、proc_open、symlink 等函数，Composer 和 php artisan 会因此报错。去「PHP设置」->「禁用函数」里删掉它们。

第二步：创建站点，运行目录必须指向 public

这一步要创建网站并把访问入口改到 public，做完后 Laravel 路由才能正常接管请求。点左侧「网站」->「创建网站」，域名填 example.com，根目录填项目根目录，例如 /www/wwwroot/laravel，PHP 版本选 8.2，同时勾选创建数据库。创建后点该站点「设置」->「网站目录」，把「运行目录」改为 /public，保存。Nginx 用户再到「伪静态」粘贴：

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

Apache 用户选 Laravel 伪静态规则，或确认 .htaccess 生效、AllowOverride All 已开启。

注意：运行目录不指到 public，会暴露 .env 和源码；访问首页 404，先查这里。

第三步：上传代码并配置 .env

这一步要上传项目并生成应用密钥，做完后 Laravel 能连上数据库。把代码传到 /www/wwwroot/laravel，用 SSH 或面板「终端」进入目录：

cp .env.example .env
php artisan key:generate

编辑 .env：APP_ENV=production、APP_DEBUG=false、APP_URL=https://example.com、DB_HOST=127.0.0.1、DB_DATABASE=库名、DB_USERNAME=用户名、DB_PASSWORD=密码。如果 php 不是 8.2，用绝对路径，例如 /www/server/php/82/bin/php artisan key:generate。

注意：DB_HOST 建议填 127.0.0.1，不要填 localhost；密码含 # 等特殊字符时加英文引号。

第四步：安装 Composer 依赖

这一步要安装 vendor 依赖，做完后框架代码完整。执行：

composer install --no-dev --optimize-autoloader

面板没有 Composer，就在「软件商店」安装，或下载 composer.phar 后执行 /www/server/php/82/bin/php composer.phar install。

注意：不要在服务器上跑 npm run dev。前端资源在本地 npm run build，把 public/build 传上去即可。

第五步：迁移数据库并设置权限

这一步要建表并让 storage 可写，做完后登录、上传等功能才正常。执行 php artisan migrate --force，旧数据用面板「数据库」->「导入」。Linux 下执行：

chown -R www:www storage bootstrap/cache
chmod -R 775 storage bootstrap/cache
php artisan storage:link

Windows 版小皮面板则右键项目目录 ->「属性」->「安全」，给 Users 写入权限。

注意：MySQL 8 默认 caching_sha2_password 可能让旧 PHP 连接失败，可改 mysql_native_password 或升级 PHP。

第六步：生产缓存、队列和计划任务

这一步要开启生产缓存并配置定时任务，做完后性能和计划任务才可靠。执行：

php artisan config:cache
php artisan route:cache
php artisan view:cache

再到面板「计划任务」->「添加任务」，类型选 Shell，周期 1 分钟，命令写：/www/server/php/82/bin/php /www/wwwroot/laravel/artisan schedule:run >> /dev/null 2>&1。队列可用 Supervisor 或计划任务跑 queue:work --stop-when-empty。

注意：改完 .env 要先 php artisan config:clear，再重新 config:cache。

第七步：验证和排错

这一步要确认站点可访问，做完后部署才算完成。访问域名：500 看 storage/logs/laravel.log；404 查伪静态和运行目录；403 查权限；502 查 PHP-FPM 是否启动、PHP 版本是否选对。HTTPS 在「网站」->「SSL」申请 Let’s Encrypt 或上传证书。

注意：上线后 APP_DEBUG=false，不要把 .env 提交到 Git。

小结

关键就几件事：PHP 版本匹配 Laravel；运行目录改成 public；Nginx/Apache 伪静态配对；开启 fileinfo、pdo_mysql 等扩展并解除禁用函数；配好 .env 和 APP_KEY；给 storage、bootstrap/cache 写权限；生产环境开缓存并加计划任务。