1. 环境准备
本文聚焦 Windows 11 上 Laravel 开发环境部署全流程教程：从安装到本地运行，一步到位，帮助开发者快速落地。在正式进入搭建步骤前，我们先明确目标和前提条件，确保后续过程顺利进行。
选择合适的开发架构 是成功的第一步。WSL2（Windows 子系统 Linux 2） 提供接近原生 Linux 的开发体验，能够无缝运行 Ubuntu 及其软件仓库中的生态，极大降低跨平台带来的配置成本。
要实现这一目标，您需要具备一台运行 Windows 11 的主机，且系统已启用 虚拟化与 WSL2 能力。通过本教程，您将从零开始完成安装、软件栈搭建、项目创建到本地运行的全流程。
1.1 为什么选择 Windows 11 + WSL2
在 Windows 11 上使用 WSL2 可以获得更接近 Linux 的文件系统和网络行为，这对 Laravel 等 PHP 框架的开发尤为重要。通过 共用网络栈，Windows 与 WSL2 之间的数据传输更加高效，调试体验更一致。
使用 WSL2 还能避免在 Windows 原生环境中安装大量依赖带来的兼容性问题。你可以在 WSL2 下执行 常见的 Linux 命令、包管理和服务，再通过浏览器在 Windows 主机上访问结果，提升开发效率。
1.2 需要的软件栈
核心软件栈包括 PHP、Composer、Node.js、Laravel 与一个数据库（如 MySQL）。这些组件在 WSL2 的 Ubuntu 环境中安装与配置后，能确保 Laravel 项目本地运行无缝对接。
为提升前端构建能力，你还需要 Node.js / npm，以及可选的 Redis、MariaDB 等缓存或数据库扩展。以下步骤将逐步覆盖这些要点。
2. 在 Windows 11 的 WSL2（Ubuntu）中搭建开发环境
为了实现稳定的 Laravel 开发环境，需要在 WSL2 的 Ubuntu 中安装与配置所需的软件栈与工具。本文将给出逐步的命令和配置示例，帮助你在本地快速完成搭建。
首先确保 WSL2 已启用并安装了 Ubuntu，这是后续安装的基础。接下来，我们安装 PHP、Composer、Node.js、MySQL 等组件，并验证版本信息以确保环境正确。
2.1 安装必要软件栈
在 WSL2 的 Ubuntu 中，执行下列命令安装 PHP、MySQL、Node.js 和 Composer 的基础依赖。请逐条执行并关注输出信息，如遇错误按提示解决即可。
sudo apt update
sudo apt upgrade -y
sudo apt install php-cli php-fpm php-mysql php-xml php-mbstring php-json php-tokenizer -y
sudo apt install mysql-server -y
sudo apt install curl unzip -y
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer
node -v || true
sudo apt install nodejs npm -y
重要点：确保 PHP 与扩展 已就绪，你可以用 php -v 和 php -m 查看版本与已加载的扩展列表。
如需使用最新版本的 Node.js，可以改用 NodeSource 的安装脚本，示例如下：建议使用当前长期版本。
curl -fsSL https://deb.nodesource.com/setup_current.x | sudo -E bash -
sudo apt-get install -y nodejs
2.2 配置 PHP 与扩展
在 Laravel 项目中，常用的 PHP 扩展包括 pdo_mysql、xml、mbstring 等。通过以下方法启用并验证：
sudo a2enmod rewrite
sudo systemctl restart apache2 # 如使用 Apache；若使用 Nginx，请跳过
php -r "echo PHP_VERSION;"
php -m | grep -E 'pdo_mysql|mbstring|xml'
若某些扩展未安装，可通过如下命令安装，例如：
sudo apt install php-pdo php-mysql php-xml php-mbstring -y
2.3 安装 Laravel 与创建项目
接下来安装 Laravel 的全局工具，并创建一个新的 Laravel 项目。全局安装后记得将 Laravel 的可执行路径加入 PATH，以便在任意目录下使用 laravel 命令。
composer global require laravel/installer
export PATH="$HOME/.composer/vendor/bin:$PATH" # 对应老版本
export PATH="$HOME/.config/composer/vendor/bin:$PATH" # 常见的新版本
laravel --version
创建一个新项目并进入项目目录：
cd ~
laravel new blog
cd blog
php artisan serve --host=0.0.0.0 --port=8000
3. 配置数据库与环境变量
数据库配置是 Laravel 项目能否正确连接的关键环节。本节将演示数据库初始化、用户权限设置，以及将数据库连接信息写入 .env 文件的过程。
确保数据库服务正在运行，并创建相应数据库与用户，以避免连接时的权限与名称冲突。
3.1 数据库创建与用户权限
以下示例在 MySQL 中创建一个名为 laravel 的数据库，以及一个专用用户用于 Laravel 项目的连接。务必将密码替换为你自己的强密码。
CREATE DATABASE laravel;
CREATE USER 'larad'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON laravel.* TO 'larad'@'localhost';
FLUSH PRIVILEGES;
关键点：确保用户名、数据库名和权限设置与后续的 .env 配置一致，以避免认证失败。
如果你使用的是本地 MySQL 服务，启动与自启动也很关键。下面的命令可以用来启动服务：
sudo service mysql start
sudo systemctl enable mysql # 设置开机自启
3.2 .env 配置 示例
在 Laravel 项目根目录找到 .env 文件，按以下示例修改数据库连接参数。注意将数据库名称、用户名和密码替换为你实际创建的值。
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=larad
DB_PASSWORD=your_password
更新完成后，运行 数据库迁移 与数据填充命令以确保应用程序能够正确访问数据表。
php artisan migrate
4. 本地运行与访问
本节聚焦如何在 Windows 11 的浏览器中通过本地地址访问 Laravel 应用，并解释如何在 WSL2 与 Windows 之间实现端口映射与网络通信。
本地开发服务器是 Laravel 内置的 Artisan 服务器，适合开发阶段使用，通过以下命令在 WSL2 中启动即可对外暴露端口。
4.1 运行本地开发服务器
在 Laravel 项目的根目录执行以下命令，服务器将监听 8000 端口，且使用 0.0.0.0 地址以便 Windows 主机访问。
php artisan serve --host=0.0.0.0 --port=8000
当看到输出 Server running 且监听 http://0.0.0.0:8000 时，你就可以在 Windows 浏览器中访问了。
如果你希望直接通过 Windows 的 localhost:8000 访问，请确保 WSL2 与 Windows 的端口映射没有被防火墙阻断。
4.2 端口映射与访问
WSL2 与 Windows 之间的网络共享 使得在浏览器中访问 http://localhost:8000 成为可行选项，但有时需要在 Windows 防火墙里允许相应端口。若使用 Docker Desktop 或其他虚拟化工具，请确保端口转发规则生效。
在浏览器中访问结果应能看到 Laravel 的欢迎页；若看到连接错误，请检查以下要点：WSL2 网络状态、端口是否被占用、防火墙设置 与 .env 数据库连接是否正常。
5. 常见问题与优化
在 Windows 11 的 WSL2 + Laravel 开发环境中，可能遇到一些常见问题。以下内容给出排查思路与简单优化方法，帮助你更稳定地进行本地开发。
性能与磁盘 I/O、PHP 配置、缓存机制
以及代码热替换 都会影响体验，合理配置可以显著提升开发效率。
5.1 性能与缓存
为提升 执行性能，可以开启 PHP 的 OPcache，并在开发阶段合理调整 error_reporting 和 display_errors 的级别，以便快速发现问题。
前端资源缓存方面，使用 Laravel Mix 或 Vite 时，启用热更新（HMR）可以缩短重新加载的时间，提升迭代速度。
# 开启 OPcache（示例，实际配置以 /etc/php/7.x/cli/php.ini 为准）
echo 'opcache.enable=1' | sudo tee -a /etc/php/7.x/cli/php.ini
5.2 常见报错与排查
常见错误多来自 数据库连接、缺少扩展、权限不足 等方面。遇到报错时，先确认 .env 的数据库配置与实际数据库信息一致，并检查 laravel.log 文件中的详细错误。
若遇到依赖安装问题，可尝试清理 Composer 缓存并重新安装依赖：composer install --no-interaction --prefer-dist，并确保网络连通性正常。
composer clear-cache
composer install --no-interaction --prefer-dist
