Laravel 与 Linux 的兼容性问题解决指南
一 环境准备与版本匹配
- 明确版本要求：Laravel 需要 PHP 7.3+（推荐 8.0+），并安装常用扩展（如 mbstring、xml、curl、zip、pdo_mysql/redis/gd 等）。
- 安装与路径：使用系统包管理器安装 Nginx/Apache、PHP-FPM、MySQL/PostgreSQL、Composer；将 Composer 加入 PATH，便于全局使用。
- 国产系统适配：在 统信 UOS、麒麟 OS、Deepin 等基于 Linux 的系统上，优先用系统源安装匹配版本的 PHP 与扩展；若扩展缺失，先安装编译依赖（如 gcc、make、php-dev/php-devel），再从 PECL 编译安装（如 redis、gd）。
- 服务与端口：部署前确认 80/443 未被占用；若与系统预装 Apache 冲突，先停用或改用其他端口。
- 基础检查命令示例：
- 查看 PHP 与扩展：
php -v、php -m | grep -E 'mbstring|xml|curl|zip|pdo_mysql|redis|gd'
- 查看服务与端口：
systemctl status nginx、ss -tlnp | grep ':80\|:443'
- Composer 安装：
curl -sS https://getcomposer.org/installer | php && sudo mv composer.phar /usr/local/bin/composer
二 部署与权限关键点
- 目录与密钥：确保项目根目录下的 storage、bootstrap/cache 可写；复制 .env.example 为 .env 并生成应用密钥：
php artisan key:generate。
- 权限设置：推荐将项目属主设为 Web 服务运行用户（Debian 系常见为 www-data，RHEL/CentOS 系常见为 nginx），并对可写目录设置宽松权限：
sudo chown -R www-data:www-data /path/to/laravel（或 nginx:nginx）sudo chmod -R 755 storage bootstrap/cache
- 依赖安装：在部署环境执行
composer install --optimize-autoloader --no-dev，上线前可清配置缓存：php artisan config:clear。
- 安全与性能：生产环境设置 APP_DEBUG=false；按需执行缓存命令：
php artisan config:cache、php artisan route:cache、php artisan view:cache。
三 Web 服务器与 PHP-FPM 配置
- Nginx 最小可用配置要点：
- 根目录指向 public；启用
try_files $uri $uri/ /index.php?$query_string; 以支撑 Laravel 路由。
- PHP 处理段使用 FastCGI，将 SCRIPT_FILENAME 设为
$realpath_root$fastcgi_script_name，确保跨目录解析正确。
- 示例片段：
root /path/to/laravel/public;try_files $uri $uri/ /index.php?$query_string;fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;（路径以实际 PHP-FPM 为准）fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
- Apache 要点：启用 mod_rewrite，虚拟主机 DocumentRoot 指向 public，并配置 AllowOverride All。
- 套接字与进程：确认 Nginx 与 PHP-FPM 使用一致的 Unix 套接字路径 或 TCP 端口；变更后重载服务：
systemctl reload nginx && systemctl reload php-fpm。
- 常见故障排查：
- 502/504：检查 PHP-FPM 是否运行、套接字路径是否一致、进程是否崩溃。
- 路由 404：确认
try_files 与 index.php 处理已生效。
- 权限被拒：确认目录属主与权限、以及 SELinux/AppArmor 未拦截。
四 数据库与文件系统兼容性
- 数据库连接失败（如 SQLSTATE[HY000] [2002] No such file or directory）：
- 将 DB_HOST=localhost 改为 DB_HOST=127.0.0.1 以强制走 TCP/IP；或显式设置套接字路径：在 .env 增加
DB_SOCKET=/tmp/mysql.sock，并在 config/database.php 的 mysql 配置中加入 'unix_socket' => env('DB_SOCKET'),。
- 权限与属主：确保运行 PHP-FPM 的用户对 storage/framework、storage/logs、bootstrap/cache 具备写权限。
- 国际化与本地化：如需中文，安装语言包（如 spatie/laravel-lang），发布语言文件并在
config/app.php 设置 'locale' => 'zh-CN'。
- 日志定位：PHP 错误通常记录在 /var/log/php-fpm.log 或 /var/log/php7.x-fpm.log；Laravel 应用日志位于 storage/logs/laravel.log。
五 国产 Linux 与 SELinux 的专项处理
- 国产系统差异：
- 包管理：有的基于 Debian 系（apt），有的基于 RHEL/CentOS 系（yum/dnf）；选择与系统版本匹配的 PHP 与扩展 版本，避免强行升级导致依赖断裂。
- 套接字路径：不同发行版或安装方式下 MySQL 套接字 可能位于 /var/run/mysqld/mysqld.sock 或 /tmp/mysql.sock，按实际修正 DB_SOCKET 或改用 127.0.0.1。
- 编译扩展：当系统源缺少扩展时，先安装编译依赖（如 build-essential/php-dev 或 gcc/make/php-devel），再从 PECL 编译安装并启用。
- SELinux 场景：
- 临时放行：
sudo setenforce 0（仅测试环境）。
- 持久化：编辑 /etc/selinux/config 将 SELINUX=enforcing 改为 SELINUX=permissive/disabled（生产环境谨慎评估）。
- 安全建议：上线前恢复 SELINUX=enforcing，并通过策略或布尔值精细化放行（如允许 httpd/php-fpm 访问项目目录与套接字），避免长期关闭。
