oh-my-zsh coffee 插件详解：在终端中快速编译、预览与剪贴板流转 CoffeeScript

oh-my-zsh 的 coffee 插件为 CoffeeScript 开发者提供了一组“写一段、立刻看到编译结果”的快捷命令（cf、cfc、cfp、cfpc），免去手动敲 coffee -peb "..." 的麻烦。本文以 plugins/coffee/README.md 为主体，结合 coffee.plugin.zsh 源码、lib/clipboard.zsh 剪贴板底层实现与 _coffee 补全脚本，完整讲清这四个命令的用法、参数含义与跨平台原理，读完即可在自己的 zsh 中熟练进行 CoffeeScript 的即席编译与剪贴板往返。

插件定位：为什么需要 cf 系列命令

插件的 README 明确说明了它的场景：编写 CoffeeScript 时，经常需要快速预览某段代码编译后的 JavaScript 输出——既可能是为了检查编译产物，也可能是为了把结果粘进不接受 CoffeeScript 的浏览器控制台执行。coffee 插件把这一步收敛成一条命令：

$ cf 'if a then b else c'
if (a) {
  b;
} else {
  c;
}

除了 cf，README 还列出了三个围绕剪贴板的变体：

命令	作用	典型场景
cf	编译并打印一段内联的 CoffeeScript	快速验证某段代码的编译结果
cfc	编译后把生成的 JS 复制到剪贴板	要把产物粘到 JS 控制台（如浏览器 DevTools）执行
cfp	从当前剪贴板内容编译并打印	编译大段/多行的剪贴板片段，避免命令行转义
cfpc	从剪贴板粘贴 → 编译 → 结果再写回剪贴板	一条命令完成“剪贴板里的 CoffeeScript 原地转成 JS”

启用插件

在 ~/.zshrc 的 plugins 数组中加入 coffee 即可，该配置格式参见 oh-my-zsh 官方模板 zshrc.zsh-template：

plugins=(coffee)

加载机制在框架入口 oh-my-zsh.sh 中：框架遍历 $plugins，对每个插件依次 source plugins/$plugin/$plugin.plugin.zsh，并优先检查 ~/.oh-my-zsh/custom 下是否存在同名覆盖文件（见 _omz_source 函数，oh-my-zsh.sh）。因此如果想定制 cf 行为，可在 ~/.oh-my-zsh/custom/plugins/coffee/coffee.plugin.zsh 放置覆盖版本，无需改动仓库本体。

另外需要注意一个隐含前提：coffee 插件只是薄封装，它调用的是 CoffeeScript 官方 CLI 工具，所以系统中必须已安装 coffee 命令（如通过 npm install -g coffee-script 或 Homebrew 等包管理器），插件本身不附带编译器。

四个命令的源码剖析

coffee.plugin.zsh 全文只有 16 行，核心实现如下：

# compile a string of coffeescript and print to output
cf () {
  coffee -peb "$1"
}
# compile & copy to clipboard
cfc () {
  cf "$1" | clipcopy
}

# compile from clipboard & print
alias cfp='cf "$(clippaste)"'

# compile from clipboard and copy to clipboard
alias cfpc='cfp | clipcopy'

可以逐条拆解其结构：

• cf 是一个 zsh 函数，把第一个参数原样传给 coffee -peb。注意源码中参数被 "$1" 双引号包裹，所以多行片段、含空格或 shell 特殊字符的代码都不会被词法拆分或 glob 展开，安全性由 zsh 引号保证。
• cfc 复用 cf：编译输出经管道送给 clipcopy。它并不重复调用 coffee 命令，保证了 cfc 与 cf 行为永远一致。
• cfp 是 alias：展开为 cf "$(clippaste)"，即先用 clippaste 把剪贴板内容写到 stdout，再用 $(...) 命令替换捕获后作为 cf 的参数。命令替换会剥掉首尾换行，多行内容则整体保留在双引号内传给 cf——这正是它适合“大段/多行片段”的原因。
• cfpc 也是 alias：展开为 cfp | clipcopy，本质上是 cf + cfc 的合成——先从剪贴板取内容编译，再把 JS 结果写回剪贴板。

从源码结构看，四个命令构成清晰的复用链：cf 是唯一真正调用 coffee 的入口，cfc、cfp、cfpc 全部在其基础上组合，因此如果 cf 可用，其余三个理论上一定可用（前提见下文剪贴板一节）。

底层原理：coffee -peb 的三个参数

cf 之所以能“一行输入、看到完整 JS 输出”，关键在于 -peb 三个开关的组合。它们的含义可从插件同目录下的补全脚本 _coffee 中得到官方说明：

• -e / --eval：把命令行字符串当作输入（pass a string from the command line as input），这正是 cf 能接受内联代码的原因；
• -p / --print：打印编译出的 JavaScript（print out the compiled JavaScript）而不是生成 .js 文件；
• -b / --bare：编译时不包裹顶层函数（compile without a top-level function wrapper）。

-b 的细节很重要：不加它时，CoffeeScript 会把整段代码包在一个 (function() { ... }) 顶层作用域里，预览或粘进浏览器控制台时会引入不必要的 IIFE 封装；加上 -b 后得到的就是“裸”的、可直接执行的 JS。这与 README 示例中输出的 if (a) { b; } else { c; } 没有被函数包裹是直接对应的。

_coffee 中还可以看到一个兼容性细节：补全脚本会调用 coffee --version 探测版本，若低于 1.6.3 才会追加 -l/--lint（JSLint 管道）与 -r/--require 这两个旧版选项的补全条目（plugins/coffee/_coffee）。这提示了该插件生态对应的 CoffeeScript CLI 大致处于 1.x 时代——如果你的 coffee 是 2.x，-peb 参数仍然有效，但补全脚本中 -n/-t/-p 互斥等细节可能与新版本的实际行为存在差异，以 coffee --help 输出为准。

剪贴板支持：来自 lib/clipboard.zsh 的跨平台实现

cfc、cfp、cfpc 依赖的两个函数 clipcopy 和 clippaste 并不是 coffee 插件自己定义的，而是 oh-my-zsh 框架级的公共能力，实现在 lib/clipboard.zsh。该文件由框架启动时无条件加载——oh-my-zsh.sh 会遍历并 source $ZSH/lib 下所有 .zsh 文件，所以任何依赖 clipcopy/clippaste 的插件（如 coffee、copybuffer、copypath 等）都可以直接调用。

detect-clipboard 函数（lib/clipboard.zsh）按如下优先级探测平台并动态定义这两个函数：

1. macOS（OSTYPE 为 darwin*）：pbcopy / pbpaste；
2. Cygwin / msys：读写 /dev/clipboard；
3. 原生 Windows（存在 clip.exe 与 powershell.exe）：clip.exe / PowerShell Get-Clipboard；
4. Wayland（设置了 $WAYLAND_DISPLAY）：wl-copy / wl-paste；
5. X11（设置了 $DISPLAY）：优先 xsel，其次 xclip；
6. SSH 转发：lemonade 或 doitclient；
7. Windows 备用：win32yank；
8. Android/Termux：termux-clipboard-set / termux-clipboard-get；
9. tmux 会话（设置了 $TMUX）：tmux load-buffer / tmux save-buffer。

其头部注释还说明：该启发式顺序与 Neovim 的剪贴板 provider 设计思路一致，并额外加了 Cygwin 支持。

两个值得注意的实现细节：

• 惰性探测 + 失败重试：clipcopy/clippaste 首次被调用时才执行 detect-clipboard（lib/clipboard.zsh）；如果启动时没探测到任何工具，函数会先重跑一次探测再执行（_retry_clipboard_detection_or_fail），全部失败则向 stderr 打印 clipcopy: Platform $OSTYPE not supported or xclip/xsel not installed 并返回 1。也就是说，在无图形环境且未安装 xclip/xsel 的纯 Linux 终端上，cfc/cfp/cfpc 会报这个错——这是使用这三个命令前必须确认的环境前提，而 cf 本身不受影响。
• clipcopy 支持管道和文件两种用法：<command> | clipcopy 复制 stdin，clipcopy <file> 复制文件内容（lib/clipboard.zsh）；clippaste 则把剪贴板内容写到 stdout，可继续管道或重定向。coffee 插件正是利用“写到 stdout”这一特性，用 $(clippaste) 捕获剪贴板文本。

命令补全：_coffee

插件目录下的 _coffee 是一个标准 zsh completion 脚本（首行 #compdef coffee），为 coffee 命令本身提供 Tab 补全，而不是给 cf 系列补全。它声明的参数分组覆盖：

• 互斥的输出模式：-n/--nodes、-t/--tokens、-p/--print（三者互斥）；
• 编译与运行：-c/--compile、-o/--output（补全目录）、-w/--watch、-i/--interactive（REPL）、-s/--stdio；
• 输入处理：-e/--eval、-b/--bare、-j/--join、--nodejs；
• 位置参数：script or directory，补全任意文件（plugins/coffee/_coffee）。

加载该补全依赖 oh-my-zsh 的 completion 机制（fpath 中包含插件目录且已执行 compinit，由 lib/completion.zsh 负责初始化）。启用 plugins=(coffee) 后，在输入 coffee 时即可获得上述选项提示；由于 cf 只是 coffee -peb 的封装，日常“内联编译 + 看结果”用 cf，而“对文件/目录做完整编译、监听、REPL”等重活仍应直接使用 coffee 原生命令。

实战组合与注意事项

把 README 的三个命令串起来，一个典型的“剪贴板工作流”是：

# 1. 编辑器里选中一段 CoffeeScript，Ctrl+Shift+C 复制
# 2. 终端里直接：
cfp        # 立即看到编译后的 JS

# 或者一步到位，把剪贴板原地替换成 JS：
cfpc
# 然后直接到浏览器控制台 Ctrl+V 粘贴执行

使用时的边界情况：

1. cf 只取第一个参数：源码中是 coffee -peb "$1"，cf 'a' 'b' 会忽略第二个参数。多行/复杂代码请放入单引号内，或改用 cfp 走剪贴板。
2. 引号内的 shell 语义："$1" 保证代码串不被 zsh 再次解释，但 CoffeeScript 字符串字面量内部若含单引号，需自行用双引号调用（cf "if a then 'x'"）或转义。
3. 剪贴板三兄弟依赖环境：cfc/cfp/cfpc 要求 lib/clipboard.zsh 能探测到至少一个剪贴板后端（macOS 自带 pbcopy/pbpaste，Linux 需 xclip/xsel/wl-copy 等），否则得到的是 stderr 报错而非静默失败。
4. cfpc 是 alias 链：其展开顺序为 cfpc → cfp | clipcopy → cf "$(clippaste)" | clipcopy，即剪贴板先被读取、编译，最后结果写回，原 CoffeeScript 内容会被 JS 覆盖。

小结

coffee 插件用 16 行源码展示了 oh-my-zsh 插件的典型写法：一个调用官方 CLI 的函数（cf）+ 若干基于 clipcopy/clippaste 组合的 alias，再配套一个针对底层命令的补全脚本。它依赖的两个关键基础设施——框架的 plugins 加载机制（oh-my-zsh.sh）与跨平台剪贴板封装（lib/clipboard.zsh）——都是仓库内的公共组件，理解它们不仅能用好 coffee 插件，也能为自研其他“命令行 + 剪贴板”工作流插件提供直接可复用的模式。