如何配置Laravel本地开发环境？

本文共计781个文字，预计阅读时间需要4分钟。

Laravel 10 要求 PHP 版本为 8.1 或更高，且以下扩展必须启用：

php -m | grep -E "(mbstring|openssl|pdo_mysql|fileinfo|xml)"

如果某项没输出，说明未启用。Windows 用户需编辑 php.ini 取消对应 extension=xxx 行的注释；macOS/Linux 用户若用 Homebrew 安装 PHP，通常执行 brew install php@8.2 后自动带全，但 php@8.2 和系统默认 php 可能冲突，建议用 which php 确认路径是否指向 brew 安装的版本。

Composer 安装后必须配国内镜像源

不配置镜像，composer create-project 极易超时或卡死在 Installing dependencies 阶段。执行：

composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/

验证是否生效：

composer config -g repo.packagist

应输出 https://mirrors.aliyun.com/composer/。注意：这个配置是全局的，不影响已有项目，但新项目依赖拉取速度会明显提升。若已卡住，可按 Ctrl+C 中断后重试，别硬等。

php artisan serve 启动失败常见原因

报错 Could not open input file: artisan：说明不在项目根目录（即含 artisan 文件的那层），或当前用户无执行权限（Linux/macOS 下偶尔发生）。

报错 Address already in use：端口被占，默认 :8000，换一个即可：

• php artisan serve --port=8001
• php artisan serve --host=127.0.0.1 --port=8080

更隐蔽的问题是 .env 缺失或 APP_KEY 为空：即使页面能打开，部分功能（如 session、加密）会异常。务必检查并运行：

php artisan key:generate

该命令只在 .env 存在且 APP_KEY 为空时才真正写入密钥。

数据库迁移前必须检查 .env 和 MySQL 连通性

php artisan migrate 报错 SQLSTATE[HY000] [1045] Access denied，大概率是 .env 里 DB_USERNAME 或 DB_PASSWORD 错了，而不是密码本身不对——Laragon/XAMPP 默认 root 用户密码为空，但很多人误填成 root。

验证连通性的最快方式不是跑 migrate，而是直接用命令行连接：

mysql -u root -h 127.0.0.1 -P 3306 -D laravel_site

若提示 Access denied，就说明 .env 的数据库凭据和实际 MySQL 设置不匹配。另外，DB_DATABASE 对应的库必须已存在，php artisan migrate 不会自动创建数据库，只建表。

APP_KEY 生成一次就够了，但很多人重复执行 key:generate 导致线上环境密钥轮换混乱；本地开发无所谓，但复制代码到测试/生产前，务必确认 .env 是否被意外提交进 Git——这是安全大忌。