VSCode运行Laravel项目：基于Sail的Docker容器化开发流

Lara vel Sail + VSCode Dev Container 堪称本地开发最省心、最一致的组合，前提是得把 .devcontainer.json 里的 dockerComposeFile 和 service 字段配对，Docker Desktop 要启动并切到 Linux 模式，挂载路径得准确，.env 里数据库主机名必须写容器服务名（比如 mysql），然后重启容器才能生效。

直说了吧：用 Lara vel Sail + VSCode Dev Container，是目前本地开发中最省心、最一致的方案。但前提是——别跳过 .devcontainer.json 里的关键字段修改，也别漏掉容器内路径映射。否则，你可能会在连不上容器、找不到命令、数据库拒绝访问这些坑里反复打转。

为什么 sail up 后 VSCode 还连不上容器？

很多人在点击 Remote-Containers: Reopen in Container 后卡在“Building image”或直接报错 Cannot connect to the Docker daemon。这种情况通常绕不开下面几个点：

• 宿主机上的 Docker Desktop 必须已经启动，并且设为 Linux 容器模式（Windows 和 macOS 都别忘了检查这一项）。
• .devcontainer/devcontainer.json 中的 "dockerComposeFile" 路径必须指向项目根目录下的 docker-compose.yml，千万别写成相对路径 ./docker-compose.yml 或绝对路径——那会直接让 VSCode 找不着北。
• 如果项目自定义了 Sail 配置（比如改动了 docker-compose.override.yml），devcontainer.json 里的 "service" 字段必须和 compose 文件里的服务名完全一致。默认情况下是 "lara vel.test"，而不是你以为的 app。
• 首次构建时，网络波动可能导致镜像拉取失败。稳妥的做法是手动运行一遍 ./vendor/bin/sail build --no-cache，先把镜像预热好。

artisan 命令在集成终端里提示“command not found”？

这大概是大多数人最容易忽略的路径陷阱。VSCode 默认终端启动的是宿主机 shell，根本不是容器内的环境。所以：

• 一定要先通过 Remote-Containers: Reopen in Container 进入容器，然后才打开终端。确认左下角状态栏显示的是 Dev Container: lara vel.test，这才表示你已经在容器里了。
• 不要站在宿主机终端里试图执行 ./vendor/bin/sail artisan。进到容器后，直接用 php artisan 或者 artisan 就行（Sail 会自动帮你 alias 好）。
• 如果还是报错，检查一下 /var/www/html 是否真的挂载了你的项目代码。devcontainer.json 里的 "mounts" 字段必须包含 "source=${localWorkspaceFolder},target=/var/www/html,type=bind,consistency=cached"，缺了它代码根本进不去容器。
• PHP 扩展缺失也会导致 artisan 启动失败，比如 pdo_pgsql。可以在容器内运行 php -m | grep pgsql 来验证扩展是否存在。

数据库连接失败：明明 sail ps 显示 mysql 在运行？

错误信息通常是 SQLSTATE[HY000] [2002] Connection refused 或 Connection timed out。根本原因很简单——Lara vel 应用连错了容器网络的地址。常见坑如下：

• .env 里的 DB_HOST 必须填容器服务名，比如 mysql，而不是 127.0.0.1 或 localhost。Sail 默认的 MySQL 服务名就是 mysql，所以直接写 DB_HOST=mysql 就行。
• PostgreSQL 用户容易踩的坑：DB_PORT 在容器内是 5432，但 DB_HOST 仍然要写 postgres（Sail 的 compose 模板里服务名是 postgres，不是 postgresql）。
• Redis 同理：REDIS_HOST=redis，别写成 127.0.0.1；而且 REDIS_PASSWORD 默认是空字符串，不是 null 也不是未设置。
• 改完 .env 后必须重启容器：./vendor/bin/sail down && ./vendor/bin/sail up -d。Lara vel 不会自动重读环境变量，别指望改完就能直接生效。

其实真正麻烦的从来不是启动命令本身，而是容器内外的路径、网络、权限三者错位时，错误信息往往不指向真实原因。比如 artisan migrate 失败，可能是 .env 写错了 DB_HOST，也可能是 storage/ 目录权限在容器内不对（这时候要进容器执行 chown -R www-data:www-data /var/www/html/storage），还可能是 MySQL 容器还没完全初始化好就急着连。这些都得靠 ./vendor/bin/sail logs mysql 和 ./vendor/bin/sail exec lara vel.test bash 一层层去验证，没法靠猜。