Laravel 12项目上线与环境配置

适用环境和上线前准备

本文面向已经开发完成的Laravel 12项目,使用Ubuntu 24.04、PHP 8.3、PHP-FPM、Nginx和Composer 2。它不适用于把其他Laravel大版本直接改成12,也不替代项目自身的安装说明。准备独立站点目录、数据库及账号、域名和HTTPS证书,保留源码版本与composer.lock。初始化和迁移期间先限制入口只允许管理员访问,登录、权限及写入验收完成后再开放。

下面以/srv/laravel-app为项目目录。Composer、Artisan及前端构建用普通部署用户执行,管理员只处理软件包和系统配置。已有面板环境按其PHP管理方式操作,不混装另一套PHP。首次部署新项目可以使用系统仓库安装:

sudo apt update
sudo apt install nginx php8.3-fpm php8.3-cli php8.3-curl \
  php8.3-mbstring php8.3-xml php8.3-zip php8.3-bcmath \
  php8.3-mysql composer unzip

一、按锁定文件安装依赖

把自己的完整项目放到目标目录,确认包含artisan、composer.json、composer.lock和public目录,并让部署用户拥有该项目。不要从网页下载来源不明的业务源码。

cd /srv/laravel-app
php -v
composer install --no-dev --prefer-dist --optimize-autoloader
composer check-platform-reqs --no-dev

依赖安装失败先核对PHP及扩展,不加--ignore-platform-reqs跳过要求。上线用install遵循锁定版本,不直接update整套依赖。项目有前端资源时,按其package.json与锁定文件在构建环境完成构建,并带上实际生成的public/build等目录。

二、设置本项目环境和权限

仅在.env不存在时从.env.example复制,然后用编辑器填写真实值。下面是需要核对的示例,密码占位必须替换:

APP_ENV=production
APP_DEBUG=false
APP_URL=https://app.example.com
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel_app
DB_USERNAME=laravel_app
DB_PASSWORD="替换为该数据库账号的密码"

数据库须提前创建,账号只授权给这个库,并与实际允许的连接来源相符。首次创建且APP_KEY为空时执行php artisan key:generate;迁移已有应用必须保留原APP_KEY,不能重新生成后让原加密数据失效。

核对PHP-FPM实际运行用户。以下仅适用于该站点使用www-data的情况,授予写权限的范围只有两个运行目录:

sudo chgrp www-data .env
chmod 640 .env
sudo chgrp -R www-data storage bootstrap/cache
find storage bootstrap/cache -type d -exec chmod 2770 {} +
find storage bootstrap/cache -type f -exec chmod 660 {} +

部署用户仍需拥有这些文件;PHP-FPM要能读取代码、穿过上级目录,但不需要修改全部源码。若使用独立FPM池,换成对应运行组,不使用777。

三、Nginx只公开public目录

在本域名已配置HTTPS的server块内合并以下应用配置,socket路径按实际PHP-FPM填写。证书准备可参考Certbot为Nginx申请证书与验证续期。

root /srv/laravel-app/public;
index index.php;

location / {
    try_files $uri $uri/ /index.php?$query_string;
}
location = /index.php {
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
    fastcgi_pass unix:/run/php/php8.3-fpm.sock;
}
location ~ \.php(?:/|$) {
    return 404;
}
location ~ /\.(?!well-known).* {
    deny all;
}

不能把root设成项目根目录,也不能把.env搬进public。保留站点原有证书与访问控制,不覆盖其他网站配置。nginx -t成功后再重载Nginx。

四、初始化数据库并验收

确认连接的是新建空库,查看项目迁移后再执行:

php artisan migrate:status
php artisan migrate --force
php artisan config:cache
php artisan about --only=environment

新建空库若提示迁移表不存在,应结合空库状态确认后再执行初始化。已有业务库必须先备份,并审核迁移影响,不能照抄空库安装步骤。配置缓存后更改.env需要重建缓存。上传若依赖公开storage链接,按项目要求执行storage:link;私密附件不能直接公开。

检查HTTPS、登录、静态资源、一个受控新增及上传,确认/.env无法下载。若项目使用队列和调度器,还要单独建立并验证对应服务,页面能打开不代表后台任务完成。失败时保留日志,恢复旧代码和配置;数据库已产生新写入时,不能直接用旧备份覆盖回退。

首次验收还应打开一个不存在的路径,确认由应用正常返回错误页且没有暴露堆栈。对外报错保持简洁,详细异常从本项目日志定位,不把服务器目录和数据库信息展示给访客。