Laravel 项目升级 PHP 8.1 需要修改哪些核心配置？

Laravel 10.x 于 2023 年 2 月发布，强制要求 PHP 8.1 或更高版本，升级时需修改至少 5 项核心配置包括扩展启用、权限设置和缓存清理。

原因分析

Laravel 框架从 9.0 版本开始要求 PHP 8.0.2 或更高，而 Laravel 10.x 将最低要求提升至 PHP 8.1。这是因为框架核心代码全面采用 PHP 8.1 的原生类型声明系统（如 int、string、void 返回类型），利用了新语言特性包括枚举和只读属性。如果 PHP 版本低于 8.1，执行 composer create-project laravel/laravel:^10.0 时会直接失败，报错信息通常为"Your PHP version (8.0.x) does not satisfy the requirements of this package"。

PHP 扩展配置修改

在 php.ini 文件中必须启用以下核心扩展，缺失任一都可能导致 artisan 命令报错：

extension=openssl
extension=pdo_mysql
extension=mbstring
extension=fileinfo
extension=tokenizer
extension=xml
extension=ctype
extension=json

目录权限与缓存配置

项目初始化后，必须设置正确的目录权限：

chown -R www:www .
find . -type d -exec chmod 755 {} \;
find . -type f -exec chmod 644 {} \;
chmod -R 775 storage bootstrap/cache

.env 文件配置注意事项：复制示例文件 cp .env.example .env 后，确保 APP_ENV=local、APP_DEBUG=true、APP_URL=http://localhost:8000 三项准确无误。.env 文件在 Laravel 启动时仅读取一次，未清缓存即修改会导致数据库连接失败等静默错误，需执行 php artisan config:clear 和 php artisan cache:clear。

Web 服务器配置调整

Nginx 伪静态规则必须修改以确保 Laravel 路由正常工作：

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

PHP 配置参数调整（位于/www/server/php/81/etc/php.ini）：

memory_limit = 512M
upload_max_filesize = 100M
post_max_size = 110M
max_execution_time = 300
date.timezone = Asia/Shanghai

注意事项

1. Laravel 项目无法启动的主因按优先级排序：PHP 版本<8.1、扩展缺失、.env 未清缓存、MySQL 凭据错误或端口占用。

2. opcache 虽然能提升性能，但在开发阶段建议暂时禁用，避免代码修改后缓存不更新的问题。

3. 使用默认命令 composer create-project laravel/laravel 会拉取最新稳定版，可能非长期支持版本，必须显式指定版本号：composer create-project laravel/laravel:^10.0 myapp。

4. Laravel 10 提供 12 个月的 Bug 修复与 18 个月的安全更新支持（截至 2024 年 9 月），升级前务必在开发环境充分测试。

5. 宝塔面板用户注意：PHP 安装时必须勾选 fileinfo 扩展，否则 Laravel 文件上传功能将无法正常工作。

参考来源

来源：Laravel 官方文档 - Laravel 10.x 重磅更新：12 大核心特性解析（2026 年 3 月 10 日）

来源：宝塔面板技术社区 - 宝塔面板+PHP8.1+Laravel9 开发环境搭建避坑指南（2026 年 3 月 30 日）

来源：Laravel 中文社区 - Laravel 如何安装配置开发环境（2026 年 4 月 15 日）

来源：GitHub Laravel 框架仓库 - 升级指南从 8.x 升级到 9.0（2026 年 4 月 30 日）