oh-my-zsh composer 插件详解：Composer 命令补全、高频别名与全局 bin 目录的 PATH 配置

本文基于 oh-my-zsh 仓库中 composer 插件说明文档 与 插件实现源码，完整解析该插件提供的三层能力：为 composer 命令提供基于真实命令列表的动态补全、覆盖高频操作的 18 个短别名，以及自动把 Composer 全局二进制的 bin 目录（vendor/bin）加入 PATH。读完本文，你可以理解每个别名的用途、补全在不同 Zsh 版本下的实现差异，以及插件缓存机制（_store_cache / _retrieve_cache）如何避免每次加载 shell 都执行一次 composer 子进程。

一、插件总览与启用方式

插件文档给出的定位是：

This plugin provides completion for composer, as well as aliases for frequent composer commands. It also adds Composer's global binaries to the PATH, using Composer if available.

即插件只做三件事：命令补全、命令别名、PATH 注入。三者都在 composer.plugin.zsh 中实现，文件结构也严格按这三个主题分段（补全、Aliases、PATH 处理）。

启用方式是把 composer 加入 ~/.zshrc 的 plugins 数组：

plugins=(... composer)

一个需要注意的前提：插件的 PATH 处理部分会调用 autoload -Uz _store_cache _retrieve_cache _cache_invalid 来读取补全缓存机制。这三个函数由 Zsh 的补全系统（compinit）在 oh-my-zsh 核心初始化阶段加载，因此 composer 必须放在 plugins 数组中由 oh-my-zsh 统一加载，而不能在 plugins 加载之前手动 source 该文件，否则缓存函数不可用。

二、别名体系：18 个高频命令的短写法

插件在 composer.plugin.zsh#L34-L51 中定义了 18 个别名，与 README 别名表 一一对应。下表完整继承原文档，并按用途分组：

2.1 基础与安装类

别名	等价命令	说明
c	composer	启动 composer
cget	curl -s https://getcomposer.org/installer | php	在当前目录安装 composer（源码中的完整写法，见 composer.plugin.zsh#L39）
csu	composer self-update	将 composer 本身更新到最新版本

cget 是插件的一个实用细节：README 表中写作 curl -s <installer> \| php，源码中则把 installer 地址固化为 https://getcomposer.org/installer。在系统未预装 composer 的环境下（比如新机器首次配置 PHP 生态），cget 一步完成引导安装，之后 c、cr 等别名即可使用。

2.2 依赖管理类

别名	等价命令	说明
cr	composer require	向 composer.json 添加新依赖包
crm	composer remove	从 composer.json 移除包
ci	composer install	解析并安装 composer.json 中的依赖
cu	composer update	更新依赖并刷新 composer.lock
co	composer outdated	列出有可用更新的已安装包
cod	composer outdated --direct	仅列出直接依赖中有可用更新的包
ccp	composer create-project	从现有包创建新项目（如脚手架 Laravel/Symfony 项目）
cs	composer show	列出可用包，支持可选过滤

2.3 自动加载（autoload）类

别名	等价命令	说明
cdu	composer dump-autoload	重新生成 autoload 映射（如手动新增类文件后）
cdo	composer dump-autoload -o	将 PSR-0/4 自动加载转为 classmap 精确映射，生成更快的自动加载器，适合生产环境

cdu 与 cdo 的区别在于 -o（optimize）参数：开发阶段用 cdu 保持动态解析，生产部署用 cdo 换取自动加载性能。

2.4 全局包管理类（COMPOSER_HOME 作用域）

别名	等价命令	说明
cgr	composer global require	在 COMPOSER_HOME 目录中执行 require，安装全局包（如 phpcs、phpunit 等 CLI 工具）
cgrm	composer global remove	在 COMPOSER_HOME 目录中移除全局包
cgu	composer global update	更新全局安装的包
cuh	composer update -d <config-home>	更新全局安装的包

这里值得指出 cuh 的一个实现细节：README 表格中的 -d <config-home> 是示意写法，源码中的实际定义（composer.plugin.zsh#L51）是

alias cuh='composer update --working-dir=$(composer config -g home)'

即在 shell 展开别名时才执行 composer config -g home 取回全局 home 目录，再以 --working-dir 传入。它解决的是「在任意目录下执行 composer update 会更新当前目录而非全局包」的问题——cgr/cgu 通过 global 子命令切换作用域，cuh 则通过 --working-dir 直接指定工作目录，两者殊途同归。

三、命令补全：按 Zsh 版本分流的实现

补全逻辑位于 composer.plugin.zsh#L1-L31，核心是一个版本分支：

## Basic Composer command completion
# Since Zsh 5.7, an improved composer command completion is provided
if ! is-at-least 5.7; then
  _composer () {
    ...
  }
  compdef _composer composer
  compdef _composer composer.phar
fi

• Zsh 5.7 及以上：if ! is-at-least 5.7 条件不成立，插件不注册任何自定义补全。源码注释明确说明「Since Zsh 5.7, an improved composer command completion is provided」——Zsh 5.7 起 compinit 默认加载的通用补全（_command_completions 机制）已能处理 composer，自定义函数反而多余。
• Zsh 5.7 以下：回退到插件自带的 _composer 函数，并注册给两个命令：

compdef _composer composer
compdef _composer composer.phar

旧版 _composer 的补全策略（composer.plugin.zsh#L4-L27）分为两级：

1. 一级：补全命令子命令。当处于第 1 个词（或第 2 个词且第 1 个词为 global）时，执行 composer list --no-ansi（通过内部变量 _comp_command1，即 composer 或 composer.phar），用 awk 从输出中截取 Available commands 段落，把「命令名 描述」压缩为 命令名:描述 形式，再交给 _describe -t commands 'composer command' subcmds 渲染成带描述的菜单。2（global 前缀）的处理保证 composer global <TAB> 时同样能列出子命令。
2. 二级：补全包名。当补全对象不是子命令时，执行 composer show -s --no-ansi，用 sed '1,/requires/d' 丢弃输出头部的 requires 区块，再 awk 提取第一列，把当前项目已安装包的名称作为补全候选——这样 composer remove <TAB> 时直接补全已有包名，避免手敲。

awk 里 gsub(/ +/, ":") 这一行还兼顾了 composer list 输出中命令与描述之间的多空格分隔，保证 _describe 能正确解析「条目:描述」结构。

四、PATH 注入：找不到 composer 时的兜底与缓存机制

4.1 两级已知目录兜底

插件加载时若 composer 不在 PATH 中，会尝试把两个社区常见目录加入 PATH（composer.plugin.zsh#L54-L61）：

if (( ! $+commands[composer] )); then
  [[ -d "$HOME/.composer/vendor/bin" ]] && export PATH="$PATH:$HOME/.composer/vendor/bin"
  [[ -d "$HOME/.config/composer/vendor/bin" ]] && export PATH="$PATH:$HOME/.config/composer/vendor/bin"

  # If still not found, don't do the rest of the script
  (( $+commands[composer] )) || return 0
fi

• $HOME/.composer/vendor/bin 是 XDG 规范普及前的旧版默认全局包目录；
• $HOME/.config/composer/vendor/bin 是遵循 XDG_CONFIG_HOME 的默认位置。

只有目录真实存在（[[ -d ... ]]）才会追加，避免向 PATH 塞入空目录。若两处都没有、composer 依然找不到，return 0 直接结束整个脚本——不执行后续的 bin 目录查询，也不产生任何副作用。

4.2 用补全缓存避免重复执行 composer

确认 composer 可用后，插件需要知道全局二进制的实际目录：

autoload -Uz _store_cache _retrieve_cache _cache_invalid
_retrieve_cache composer

if [[ -z $__composer_bin_dir ]]; then
  __composer_bin_dir=$(composer global config bin-dir --absolute 2>/dev/null)
  _store_cache composer __composer_bin_dir
fi

export PATH="$PATH:$__composer_bin_dir"
unset __composer_bin_dir

（composer.plugin.zsh#L64-L76）

这段代码的关键点是每个 shell 启动都只读缓存、不重复跑子进程：

1. _retrieve_cache composer 从 oh-my-zsh 的补全缓存目录（通常由 ~/.zcompdump 所在的 ZSH_CACHE_DIR 管理）恢复上次缓存的 __composer_bin_dir；
2. 仅当缓存为空时才执行 composer global config bin-dir --absolute（这是唯一会真正调用 composer 的地方，2>/dev/null 吞掉可能出现的警告输出），并用 _store_cache 写回缓存；
3. 最后追加到 PATH，并 unset __composer_bin_dir 避免污染全局命名空间。

这套 _store_cache / _retrieve_cache 模式并非 composer 插件独创，oh-my-zsh 中 bazel 插件、docker 补全、grunt 插件、gitignore 插件 等都采用同样的做法缓存「执行成本高且变化不频繁」的查询结果。从源码结构看，其效果是：首次（或缓存失效后）付出一次 composer 子进程的代价，之后每次开 shell 都是纯本地读文件。

五、典型工作流示例

结合本文的别名与 PATH 能力，一个典型的 PHP 项目日常流程可以压缩为：

# 初始化项目并引入依赖
ccp laravel/laravel my-app
cd my-app
ci            # composer install，按 composer.lock 安装依赖

# 日常开发
cr ramsey/uuid          # 添加依赖
co              # 查看哪些包可以升级
cod             # 只看直接依赖的升级
cdu             # 手动加了类文件后重新生成 autoload

# 安装全局 CLI 工具（安装后立即可用，因为全局 bin 目录已在 PATH 中）
cgr phpunit/phpunit
phpunit --version     # 无需再配置 PATH

# 生产发布前
cdo             # classmap 优化自动加载

其中 cgr 安装全局包后命令「立即可用」，依赖的正是第四节描述的 PATH 注入——这也是插件把「别名」和「PATH」绑在一起提供的原因：只加别名不加全局 bin 目录，cgr 装好的工具仍然敲不出来。

六、小结

能力	实现位置	关键点
18 个命令别名	composer.plugin.zsh#L34-L51	覆盖安装、依赖管理、autoload、全局包四类场景
动态命令/包名补全	composer.plugin.zsh#L1-L31	Zsh 5.7+ 交给系统原生补全，旧版回退到解析 composer list / composer show -s 输出的 _composer
全局 bin 目录 PATH 注入	composer.plugin.zsh#L54-L76	两级旧/XDG 目录兜底；_store_cache 缓存 composer global config bin-dir 结果，避免每次启动 shell 执行子进程

插件作者为 Daniel Gomes，来源与完整说明见 plugins/composer/README.md。整个插件不引入任何第三方依赖，全部逻辑约 76 行，是理解 oh-my-zsh 插件「别名 + compdef 补全 + 缓存式 PATH 配置」这一标准组合的很好范本。