---

一、 全新安装：同时新建项目与 Sail 环境

如果你想从零开始创建一个全新的 Laravel 12 项目并直接包含 Sail，这是最快的方法。

1. 执行安装脚本

在你的 PhpstormProjects 目录下运行以下命令：

# example-app 是你的项目名，你可以随便改
curl -s "https://laravel.build/example-app" | bash

💡 提示： 你可以通过 URL 参数指定需要的服务。例如，如果你需要 MySQL 和 Redis：
curl -s "https://laravel.build/example-app?with=mysql,redis" | bash

2. 赋予权限并启动

安装完成后，进入目录并启动：

cd example-app

# 启动 Sail (第一次运行会下载大量镜像，请保持网络畅通)
./vendor/bin/sail up -d

---

二、 在现有项目中集成 Sail

如果你已经有一个像 example-app 这样的文件夹，但里面还没有 Sail，请按以下步骤操作：

1. 安装 Sail 扩展包

在项目根目录下，确保你已经通过 composer install 装好了基本依赖，然后运行：

composer require laravel/sail --dev

2. 生成 Sail 配置文件

运行以下命令来生成 docker-compose.yml：

php artisan sail:install

终端会询问你想要支持哪些服务（如 mysql, redis, meilisearch 等），用空格选择后回车。

3. 配置 .env

Sail 会自动修改你的 .env 文件。请检查以下项以确保它们指向 Docker 容器而不是本地：

• DB_HOST=mysql
• MEMCACHED_HOST=memcached
• REDIS_HOST=redis

---

三、 Sail 的日常使用技巧

在 Sail 环境下，你不再需要在本地运行 php 或 npm，所有命令都要通过 sail 前缀运行。

1. 设置别名 (强烈建议)

为了不用每次都打 ./vendor/bin/sail，在终端运行：

alias sail="./vendor/bin/sail"

(想永久生效？把这行加到你的 ~/.bashrc 里，然后 source ~/.bashrc)

2. 常用命令对比表

传统命令	Sail 命令	作用
php artisan migrate	sail artisan migrate	运行数据库迁移
composer install	sail composer install	安装 PHP 依赖
npm install	sail npm install	安装前端依赖
npm run dev	sail npm run dev	启动 Vite 开发服务器
php -v	sail php -v	查看容器内的 PHP 版本

---

四、 在 Ubuntu 24.04 部署时的关键点

1. 解决 Docker 权限问题

如果你运行 sail up 提示权限不足，请确保你的普通用户已加入 docker 组：

sudo usermod -aG docker $USER
# 然后注销系统并重新登录

2. 端口冲突

如果你的 Ubuntu 本地已经装了 MySQL 或 Nginx，可能会占用 3306 或 80 端口。

• 解决方法：修改 .env 文件，手动指定 Sail 映射到本地的端口：

APP_PORT=8080
FORWARD_DB_PORT=33060

3. 访问项目

启动后，直接在浏览器访问：http://localhost (或者你设置的 APP_PORT)。

---

4. 重点：项目适用选择？

根据项目复杂度来选：

• 个人练习/快速原型：
  直接 curl -s "https://laravel.build/example-app" | bash。
  使用 SQLite，省电省内存，电脑不发烫。
• 正规项目开发：
  curl -s "https://laravel.build/example-app?with=mysql,redis,mailpit" | bash。
• MySQL：数据持久化，模拟真实环境。
• Redis：处理 Laravel 队列和缓存。
• Mailpit：这是一个非常好用的工具，Sail 自带，可以让你在本地拦截并查看 Laravel 发出的测试邮件（非常直观）。

---

5. 安装 SQLite 版后，如何修改？

你不需要重新创建项目！在现有项目中，只需运行：

php artisan sail:install

它会弹出一个列表，问你：“嘿，你想添加哪些服务？”。

1. 你勾选 MySQL 和 Redis。
2. 它会自动修改你的 docker-compose.yml。
3. 运行 sail up -d，它就会自动去拉取 MySQL 的镜像并跑起来。

---

五、 总结部署流程

1. 环境准备：Ubuntu 24.04 + Docker + Docker Compose。
2. 初始化：laravel.build 脚本或 sail:install。
3. 启动：sail up -d。
4. 开发：所有 php, composer, npm 命令前加 sail。