企业官网建设流程全解析

zsh-artisan Docker深度指南：如何自动识别compose文件并智能调用Sail与docker compose

【免费下载链接】zsh-artisanLaravel artisan plugin for zsh to help you to run artisan from anywhere in the project tree, with auto-completion, and it can automatically open files created by artisan!项目地址: https://gitcode.com/gh_mirrors/zs/zsh-artisan

zsh-artisan 是一款专为 Laravel 项目打造的 zsh 插件，让你在项目的任意子目录中直接运行artisan命令，并自带 Tab 自动补全。它最被低估的能力之一，是Docker 环境的智能感知：插件会自动识别项目根目录下的 compose 文件，判断项目是否使用 Laravel Sail，并在docker compose与docker-compose之间自动选择可用命令，帮你把 artisan 命令精准地送进容器里执行 🐳

工作原理：一次命令背后的三步决策

当你敲下artisan migrate时，插件的核心逻辑 artisan.plugin.zsh 会依次完成三次判断：

1. 向上查找 artisan：从当前目录一路查到根目录，确认你身处 Laravel 项目（第 60-73 行的_artisan_find函数）
2. 扫描 compose 文件：在 artisan 所在目录检测是否存在 compose 配置文件
3. 选择执行方式：根据 compose 文件内容决定用php、sail还是docker compose执行

整个决策过程在 artisan.plugin.zsh 第 18-36 行完成，无需你做任何配置。

自动识别 compose 文件的规则

插件只检查artisan 所在目录的当前层（maxdepth 1，即项目根目录），依次匹配这四种文件名（源码第 18 行）：

• compose.yaml
• compose.yml
• docker-compose.yaml
• docker-compose.yml

命中任意一个即视为 Docker 项目。这也是为什么 Laravel Sail 项目必须把docker-compose.yaml放在项目根部——放在docker/子目录里是检测不到的。

智能调用 Sail：靠一个环境变量识别

找到 compose 文件后，插件并不会盲目使用docker compose exec，而是先检查它是否是Laravel Sail项目。判断方式非常直接：在 compose 文件中查找环境变量LARAVEL_SAIL: 1（源码第 24-25 行）。

• 有该标记→ 走vendor/bin/sail artisan ...，由 Sail 接管执行
• 没有该标记→ 走通用 docker compose 流程

为什么 Sail 要特殊对待？因为 Sail 封装了服务依赖编排（自动确保 Nginx、MySQL 等配套服务就绪），直接docker compose exec反而容易踩到服务未就绪的坑。

兼容新旧命令：docker compose vs docker-compose

Docker 从 Compose V2 起把命令合并成了docker compose，而旧版仍需docker-compose。插件通过_docker_compose_cmd函数（源码第 85-91 行）优雅地解决了这个兼容问题：

• 先静默执行一次docker compose
• 成功 → 使用新语法docker compose
• 失败 → 回退到旧语法docker-compose

这样无论你是 Docker Desktop 最新版还是多年前的老环境，插件都能自动适配 ✅

服务名匹配：如何知道 exec 进哪个容器

compose 项目里可能有十几个服务，插件用一条正则来锁定 Laravel 应用容器（源码第 28 行）：

app | php | api | workspace | laravel.test | webhost

这覆盖了绝大多数 Laravel 项目的命名习惯。执行命令形如：

docker compose exec app php artisan migrate

还有一个容易被忽略的细节：插件会判断当前终端是否为 TTY（源码第 29-34 行）。交互式终端下直接exec，而在 Tab 补全触发等非交互场景下自动追加-T参数，避免补全卡住或容器异常挂起。

实际效果对比

在tests/Feature目录深处，假设项目使用 Sail：

$ pwd ~/MyProject/tests/Feature $ artisan make:model MyAwesomeModel Model created successfully.

你不需要cd回项目根目录，不需要写./vendor/bin/sail artisan，也不用纠结本机是docker compose还是docker-compose——插件全部代劳。

快速安装

以 oh-my-zsh 为例，克隆仓库到自定义插件目录（注意目录名用artisan而非仓库名）：

git clone https://gitcode.com/gh_mirrors/zs/zsh-artisan.git "${ZSH_CUSTOM:-~/.oh-my-zsh/custom}"/plugins/artisan

然后在~/.zshrc的plugins=(...)中加入artisan即可，插件主文件为仓库根目录的 artisan.plugin.zsh。

常见问题

Q：检测到 compose 文件但容器没启动，命令会怎样？命令会原样透传给 docker，报出标准的 "no such service/container" 错误——插件不会替你启动容器，请先sail up或docker compose up -d。

Q：为什么我的容器名没被匹配到？如果你的服务名不在app/php/api/workspace/laravel.test/webhost之列，插件会跳过 Docker 流程报错。此时建议重命名服务，或直接用sail artisan手动执行。

Q：非 Sail 项目还能享受哪些能力？任意 compose 项目只要有匹配的服务名，即可在任意子目录运行artisan，Tab 补全同样基于容器内artisan list实时拉取，自定义命令也能被识别。

小结

zsh-artisan 把"在 Docker 环境里跑 artisan"这件繁琐的事压缩成了三步自动决策：认文件、认 Sail、认命令语法。配合自动补全与make:*后自动打开新建文件的特性（设置ARTISAN_OPEN_ON_MAKE_EDITOR即可开启），它是 Laravel 容器化开发工作流里一个轻量却实用的加速器。

【免费下载链接】zsh-artisanLaravel artisan plugin for zsh to help you to run artisan from anywhere in the project tree, with auto-completion, and it can automatically open files created by artisan!项目地址: https://gitcode.com/gh_mirrors/zs/zsh-artisan