Debian与Laravel的集成开发环境搭建

在 Debian 上搭建 Laravel 开发环境

一 环境准备与版本选择

• 更新系统并安装常用工具：sudo apt update && sudo apt upgrade -y && sudo apt install -y curl git unzip
• 选择稳定且受支持的 PHP 版本（推荐 8.1/8.2/8.3），并安装所需扩展（CLI、FPM、MySQL、JSON、Common、Zip、GD、Mbstring、Curl、XML、BCMath 等）。
• Web 服务器二选一：Nginx（轻量高性能）或 Apache（配置直观）；数据库可选 MySQL 或 MariaDB。
• Debian 与 Laravel 的兼容性良好，按步骤安装与配置即可稳定运行。

二 安装与配置步骤

• 安装 PHP 与扩展（以 PHP 8.2 为例，可按需替换为 8.1/8.3）
  • sudo apt install -y php php-cli php-fpm php-mysql php-zip php-gd php-mbstring php-curl php-xml php-bcmath
• 安装 Composer
  • curl -sS https://getcomposer.org/installer | php
  • sudo mv composer.phar /usr/local/bin/composer
  • sudo chmod +x /usr/local/bin/composer
• 安装并启动数据库
  • MySQL：sudo apt install -y mysql-server；安装后执行 sudo mysql_secure_installation
  • MariaDB：可添加官方仓库后安装 sudo apt install -y mariadb-server；执行 sudo mysql_secure_installation
• 创建数据库与用户（示例）
  • mysql -u root -p
  • CREATE DATABASE laravel_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
  • CREATE USER ‘laravel_user’@‘localhost’ IDENTIFIED BY ‘StrongPass!’;
  • GRANT ALL PRIVILEGES ON laravel_db.* TO ‘laravel_user’@‘localhost’;
  • FLUSH PRIVILEGES; EXIT;
• 安装 Laravel
  • 建议将项目放在 /var/www/（示例：laravel.test）
  • composer create-project --prefer-dist laravel/laravel laravel.test
• 配置 Web 服务器
  • Nginx 示例（/etc/nginx/sites-available/laravel.test）
    • server {
      • listen 80;
      • server_name laravel.test;
      • root /var/www/laravel.test/public;
      • index index.php index.html;
      • 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;
        • fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        • include fastcgi_params;
      • }
      • location ~ /.ht { deny all; }
    • }
    • 启用站点：sudo ln -s /etc/nginx/sites-available/laravel.test /etc/nginx/sites-enabled/
    • 检查并重载：sudo nginx -t && sudo systemctl reload nginx
  • Apache 示例
    • 启用重写：sudo a2enmod rewrite
    • 配置虚拟主机（/etc/apache2/sites-available/laravel.test.conf），设置 DocumentRoot 为 /var/www/laravel.test/public，并在 中 AllowOverride All
    • 启用站点：sudo a2ensite laravel.test.conf && sudo systemctl reload apache2
• 配置 Laravel 环境
  • cp .env.example .env
  • 编辑 .env：DB_CONNECTION=mysql；DB_HOST=127.0.0.1；DB_PORT=3306；DB_DATABASE=laravel_db；DB_USERNAME=laravel_user；DB_PASSWORD=StrongPass!
  • 生成密钥：php artisan key:generate
  • 可选（开发环境）：php artisan config:cache；php artisan route:cache；php artisan view:cache
• 设置文件权限
  • sudo chown -R www-data:www-data /var/www/laravel.test
  • sudo chmod -R 755 /var/www/laravel.test
  • sudo chmod -R 775 /var/www/laravel.test/storage /var/www/laravel.test/bootstrap/cache
• 访问测试
  • 本地 hosts：echo “127.0.0.1 laravel.test” | sudo tee -a /etc/hosts
  • 浏览器访问：http://laravel.test

三 开发与性能优化

• PHP-FPM 与进程管理
  • 确认运行用户与组为 www-data:www-data（/etc/php/8.2/fpm/pool.d/www.conf）
  • 按需调整 pm.max_children、pm.start_servers、pm.min_spare_servers、pm.max_spare_servers
  • 重启：sudo systemctl restart php8.2-fpm
• PHP 关键参数（/etc/php/8.2/fpm/php.ini）
  • upload_max_filesize = 20M；post_max_size = 20M；memory_limit = 256M；max_execution_time = 300
  • opcache.enable=1；opcache.memory_consumption=128；opcache.interned_strings_buffer=8；opcache.max_accelerated_files=4000；opcache.validate_timestamps=1（开发）；opcache.validate_timestamps=0（生产）
• Composer 与镜像
  • 国内网络可设置镜像加速：composer config --global repo.packagist composer https://mirrors.aliyun.com/composer/
• 前端资源（可选）
  • 安装 Node.js 与 NPM（示例）：curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt-get install -y nodejs
  • 安装依赖与编译：npm install && npm run dev（或 npm run build 用于生产）

四 常见问题与排查

• 403/404 或路由不生效
  • Nginx：确认 root 指向 public；location / 使用 try_files；.php 段 fastcgi_pass 与 php.ini 一致
  • Apache：确认 AllowOverride All 与 mod_rewrite 已启用
• 权限错误
  • 确保 storage、bootstrap/cache 对 www-data 可写（推荐 775，而非 777）
• 数据库连接失败
  • 核对 .env 中 DB_HOST/DB_PORT/DB_DATABASE/DB_USERNAME/DB_PASSWORD；确保数据库与用户已创建并授权
  • 测试连接：php artisan tinker；DB::connection()->getPdo()
• Composer 安装慢或失败
  • 使用国内镜像源；必要时更换网络或代理
• 内部服务器错误 500
  • 查看日志：tail -f storage/logs/laravel.log；开启调试：APP_DEBUG=true（仅开发环境）
• 快速本地开发替代
  • 使用内置服务器：php artisan serve（默认 http://127.0.0.1:8000）

五 安全与上线建议

• 强制 HTTPS（Let’s Encrypt）
  • sudo apt install -y certbot python3-certbot-nginx
  • sudo certbot --nginx -d laravel.test（按提示完成证书申请与自动续期配置）
• 最小权限与隔离
  • Web 服务以 www-data 运行；数据库用户仅授予目标库权限；禁止在生产使用 APP_DEBUG=true
• 防火墙与端口
  • 仅开放必要端口（如 80/443）；数据库端口（3306）仅本地监听
• 备份与更新
  • 定期备份数据库与代码；保持系统、PHP、Composer、Nginx/Apache 与依赖包为最新稳定版本