Laravel Sail 开发环境部署一把过（日常使用篇）

(Updated: )
Laravel
, , ,

容器化开发范式

迁移至 Sail 环境后，开发者的核心工作流将发生本质变化：从调用本机二进制文件转向调用容器内运行时。

Sail 本质上封装了 docker-compose exec 指令。所有开发命令均应通过 sail 代理执行，以确保运行环境与生产环境（容器镜像）的高度一致性。

映射关系示例：

本地命令 （Deprecated） 容器化命令 （Recommended） 执行上下文
php artisan ... sail artisan ... laravel.test 容器 （PHP CLI）
composer ... sail composer ... laravel.test 容器 （Composer）
npm run ... sail npm run ... laravel.test 容器 （Node）
mysql sail mysql mysql 容器

1. 后端工作流：Artisan & Composer

1.1 Artisan CLI

在容器内执行 Artisan 命令，无需在宿主机配置 PHP 环境。

1
2
3
4
5
6
7
8
# 生成资源 （Controller, Model, etc.）
sail artisan make:model Order -m

# 执行数据库迁移
sail artisan migrate

# 开启队列监听
sail artisan queue:work

1.2 依赖管理

使用 Sail 管理依赖可解决 PHP 版本不匹配问题（例如宿主机 PHP 8.0 而项目需 PHP 8.2）。

1
2
3
4
5
6
7
8
# 安装生产依赖
sail composer require guzzlehttp/guzzle

# 安装开发依赖
sail composer require laravel/pint --dev

# 执行自动加载优化
sail composer dump-autoload -o

2. 前端工作流：Node & Vite

Sail 默认集成了 Node.js 运行时，支持现代化的前端构建流程。这意味着宿主机也无需安装 Node/NPM。

1
2
3
4
5
6
7
8
# 安装前端依赖
sail npm install

# 启动开发服务器 （HMR hot-reload enabled）
sail npm run dev

# 构建生产资源
sail npm run build

Sail 会自动处理 Docker 端口映射（默认 5173），确保 WSL2 中的 Vite Server 可被宿主机浏览器访问。

3. 服务生命周期管理

基于 Docker Compose 的服务治理。

  • 启动服务栈 （Detached Mode）:
    1
    sail up -d
  • 停止服务栈:
    1
    sail stop
  • 查看容器状态:
    1
    sail ps
    Output 示例:
    1
    2
    3
    NAME                    COMMAND                  STATUS              PORTS
    example-app-laravel.test-1   "start-container"        Up                  0.0.0.0:80->80/tcp
    example-app-mysql-1          "docker-entrypoint..."   Up                  0.0.0.0:3306->3306/tcp

4. 容器访问与调试

4.1 Shell Access

在特定场景下（如检查日志、手动调试脚本），需直接进入容器 Shell：

1
2
3
4
5
# 以 workspace 用户 （sail） 进入应用容器
sail shell

# 以 root 用户进入 （主要用于安装系统级依赖）
sail root-shell

4.2 临时站点共享 （Expose）

基于 ngrok 或 expose 的隧道服务，将本地开发环境暴露至公网，便于 Webhook 调试或远程演示。

1
sail share

执行后将获得一个 http://<random>.sharedwithexpose.com 的公网链接。

总结

Sail 构建了一套完整的 容器化工具链 （Containerized Toolchain）。通过简单的 CLI 封装，它屏蔽了 Docker 底层的复杂性，同时保留了容器化开发的所有优势：隔离、一致、可移植。

在下一章《疑难杂症篇》中，我们将深入解决 Docker 环境下常见的运行时问题（网络、IO、权限）。