wsl2中安装laravel需先确保wsl2版本为2且运行正常，更新内核、切换国内apt/composer源、安装php 8.2+扩展，推荐用sail一键部署；手动安装须注意php版本、权限、artisan绑定0.0.0.0及离线场景加--ignore-platform-reqs。
在WSL2（Ubuntu 22.04/24.04）中安装Laravel框架时，常因网络卡顿、PHP版本不匹配、Composer源不可达、权限混乱或systemd缺失导致项目创建失败、vendor目录为空、artisan命令报错、sail启动崩溃——这些问题不是配置错误，而是环境链断裂的必然结果。
确认WSL2基础环境就绪
先验证WSL2是否真正可用：打开Windows Terminal，运行 wsl -l -v，确保Ubuntu发行版状态为 Running 且版本列为 2；若显示 1 或 Stopped，执行 wsl --set-version Ubuntu-22.04 2 并等待转换完成。这一步跳过会导致后续所有Docker和Laravel Sail操作静默失败。
检查内核更新：运行 wsl --update，避免因旧版WSL2内核不支持cgroup v2而使Docker Desktop无法启动容器。
【必须关闭Windows代理软件（如Clash、Surge）再执行wsl --update】，否则会触发403 Forbidden或“Failed to fetch”错误，且错误日志不提示代理干扰。
安装并切换国内PHP与Composer源
Ubuntu默认源在国内极慢，直接运行 sudo apt update 常卡在 Hit:5 https://archive.ubuntu.com/ubuntu ... 超过10分钟。需手动替换为阿里云镜像：
编辑源列表：sudo nano /etc/apt/sources.list，将所有 archive.ubuntu.com 和 security.ubuntu.com 替换为 mirrors.aliyun.com/ubuntu；保存后执行 sudo apt update && sudo apt upgrade -y。
安装PHP 8.2+及必要扩展：sudo apt install -y php8.2-cli php8.2-mbstring php8.2-xml php8.2-zip php8.2-curl php8.2-bcmath php8.2-opcache。注意：Laravel 11要求PHP ≥8.2，Ubuntu 22.04默认PHP是8.1，不升级会导致 composer create-project 直接终止并报错“Your requirements could not be resolved”。
配置Composer全局镜像源：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/。这步不做，create-project 会在下载laravel/framework时超时退出，且错误提示模糊为“Could not parse version constraint”，实际是GitHub raw链接无法访问。
用Sail快速初始化Laravel项目（推荐）
这是目前在WSL2中最稳定、最省坑的路径，绕过本地PHP环境依赖和Nginx配置陷阱。
第一步：进入目标目录，例如 cd /home/username/projects；
第二步：执行一键安装命令：curl -s "https://laravel.build/example-app" | bash；
第三步：进入项目目录：cd example-app；
第四步：启动开发环境：./vendor/bin/sail up -d；
这四步走完，Laravel应用即在 http://localhost 可访问。整个过程不依赖宿主机PHP、不修改系统PATH、不配置Nginx虚拟主机，所有服务（PHP-FPM、MySQL、Redis、MailHog）均由Docker容器托管，与WSL2内核兼容性最佳。
⚠️ 注意：首次运行 sail up 时若提示 ERROR: failed to solve: rpc error: code = Unknown desc = server misbehaving，说明Docker Desktop未启用WSL2后端——需打开Docker Desktop设置 → General → 勾选 Use the WSL 2 based engine，再重启Docker。
手动安装Laravel（仅限调试或离线场景）
方法一：使用Composer全局安装（适合已配好PHP环境）
运行 composer create-project laravel/laravel myapp --prefer-dist；
进入目录后立即执行 php artisan key:generate，否则访问首页会报 Your app key is missing；
设置storage和bootstrap/cache可写：sudo chmod -R 775 storage bootstrap/cache；
启动内置服务器：php artisan serve --host=0.0.0.0:8000，然后在Windows浏览器中访问 http://localhost:8000（非 http://127.0.0.1:8000，因WSL2网络需绑定0.0.0.0）。
方法二：离线安装（当网络完全不可用）
提前在能联网的机器上执行 composer create-project laravel/laravel myapp --no-install，再用 composer archive 打包；
将压缩包传入WSL2，解压后运行 composer install --ignore-platform-reqs；
【务必加 --ignore-platform-reqs，否则因PHP扩展检测失败而中断】。
