Debian装Laravel要注意啥

在 Debian 上部署 Laravel，核心要注意 PHP 版本与扩展、权限、Web 服务器、Composer、环境变量、队列/定时任务 这几块。下面按实际部署流程给你一个实战清单。

一、系统准备

sudo apt update
sudo apt upgrade -y

建议系统：

Debian 11 (Bullseye) ✅
Debian 12 (Bookworm) ✅（推荐）

二、PHP（最关键）

Laravel 对 PHP 版本要求较新，一定要先确认版本。

1️⃣ 查看 Laravel 要求的 PHP 版本

例如：

Laravel 10 → PHP ≥ 8.1
Laravel 11 → PHP ≥ 8.2

2️⃣ 安装 PHP（以 PHP 8.2 为例）

Debian 默认源 PHP 可能较旧，建议用 sury 源：

sudo apt install -y curl wget gnupg2 ca-certificates lsb-release apt-transport-https
curl -sSL https://packages.sury.org/php/README.txt

添加源：

wget -qO - https://packages.sury.org/php/apt.gpg | sudo apt-key add -
echo "deb https://packages.sury.org/php/ $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/sury-php.list
sudo apt update

安装 PHP 及常用扩展：

sudo apt install -y php8.2 php8.2-cli php8.2-fpm \
php8.2-mysql php8.2-pgsql php8.2-sqlite3 \
php8.2-curl php8.2-mbstring php8.2-xml \
php8.2-zip php8.2-gd php8.2-intl php8.2-bcmath

✅ 常见坑

少装 mbstring / xml / curl → Laravel 直接报错
用 php -m 检查扩展

三、Web 服务器（Nginx 推荐）

1️⃣ 安装 Nginx

sudo apt install -y nginx

2️⃣ Nginx 配置示例

server {
    listen 80;
    server_name example.com;
    root /var/www/laravel/public;

    index index.php;

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

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    }

    location ~ /\.ht {
        deny all;
    }
}

✅ 注意

root 必须指向 public
否则会暴露 .env

四、Composer

curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer
composer --version

✅ 建议：

用 Composer 2
生产环境不要装 dev 依赖：

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

五、项目部署

1️⃣ 拉代码

cd /var/www
git clone your_repo laravel
cd laravel
composer install

2️⃣ 环境配置

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

3️⃣ 权限（非常容易出问题）

sudo chown -R www-data:www-data /var/www/laravel
sudo chmod -R 755 /var/www/laravel
sudo chmod -R 777 storage bootstrap/cache

✅ 正确做法（更安全）：

sudo setfacl -R -m u:www-data:rwx storage bootstrap/cache

六、数据库

MySQL / MariaDB

sudo apt install -y mariadb-server

创建数据库：

CREATE DATABASE laravel;
CREATE USER 'laravel'@'localhost' IDENTIFIED BY 'password';
GRANT ALL ON laravel.* TO 'laravel'@'localhost';
FLUSH PRIVILEGES;

然后：

php artisan migrate

七、生产环境优化

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

⚠️ 注意：

开发环境不要 cache
改 .env 后一定清缓存

八、队列 / 定时任务（很多人忽略）

队列

sudo apt install -y supervisor

Supervisor 示例：

[program:laravel-worker]
command=php /var/www/laravel/artisan queue:work
autostart=true
autorestart=true
user=www-data

定时任务

crontab -e

* * * * * php /var/www/laravel/artisan schedule:run >> /dev/null 2>&1

九、常见坑总结（重点）

问题	原因
500 错误	storage 没权限
页面空白	root 没指向 public
路由无效	Nginx try_files 配置错
artisan 报 PHP 版本低	系统 PHP 太旧
.env 不生效	缓存没清

十、推荐组合（稳定）

✅ Debian 12 + PHP 8.2 + Nginx + MariaDB + Composer 2

如果你愿意，我可以：

给你 一步步从 0 到上线 的完整命令
帮你 排查 500 / 403 / 404 错误
给你 Docker / 非 Docker 两种方案

你现在用的是 Debian 几？Laravel 几？