Oh My Fish 完整实战指南:Fish Shell 框架的安装、命令、配置与插件开发

原创2026-09-22 10:36:372,342 阅读
文章标签:CLI包管理器

Oh My Fish 完整实战指南:Fish Shell 框架的安装、命令、配置与插件开发

Oh My Fish(OMF)是面向 Fish Shell](http://fishshell.com) 的框架,为核心基础设施,用于安装能够扩展或改变 Shell 外观的软件包(packages),同时帮助开发者统一管理配置、主题与插件。本指南以仓库根目录 [README.md 为主体,结合 init.fish、lib/require.fish、lib/autoload.fish 以及 pkg/omf 下的命令实现源码,系统讲解从安装、日常命令、启动机制、Dotfiles 管理到插件/主题创建的全流程,读完即可上手安装 OMF 并编写自己的第一个插件。

维护状态提示:Oh My Fish 已经多年未维护,部分功能可能不适用于你的环境,少量主题和包目前存在损坏,代码也亟待大规模重构;当前维护者精力有限,若你有意成为维护者,可发送邮件至 oh-my-fish [at] googlegroups.com。本文以当前仓库实际内容为准,安装与使用前请知悉该前提。

一、Oh My Fish 是什么

Oh My Fish 提供核心基础设施,允许你安装用于扩展或修改 Shell 外观的软件包。它的定位是:快速(fast)、可扩展(extensible)、易于使用(easy to use)。从仓库目录结构可以看出,框架本体由 init.fish(启动入口)、lib/(核心库:自动加载与依赖加载)、pkg/omf(omf 命令实现)、templates/config.fish(安装模板)等组成,全部用 Fish 脚本实现,不依赖任何编译产物。

框架中的包(package)分为三大类(见 docs/en-US/FAQ.md):

  1. 配置工具类:如在启动时检测系统是否存在 pyenv 并代为执行初始化命令的包;
  2. 主题类:改变提示符外观,如默认的 default 主题(含右侧提示符)以及文档中列举的 agnoster、bobthefish 等数十款主题(完整列表见 docs/Themes.md);
  3. 传统 Shell 工具类:如跨 Linux/macOS 的剪贴板工具包。

使用 OMF 并不要求你先学习任何额外知识:安装后可以像平时一样继续使用 Fish,想深入时随时输入 omf help 查看帮助。

二、安装与升级

2.1 环境要求

  • fish shell,版本 2.2 或更高;
  • git,版本 1.9.5 或更高。

2.2 默认安装

在终端中直接运行(使用默认配置开始):

curl https://raw.githubusercontent.com/oh-my-fish/oh-my-fish/master/bin/install | fish

该命令会下载安装脚本并开始安装。

2.3 自定义安装路径

先下载安装脚本,再指定安装路径与配置路径:

curl https://raw.githubusercontent.com/oh-my-fish/oh-my-fish/master/bin/install > install
fish install --path=~/.local/share/omf --config=~/.config/omf

其中 --path 对应 OMF 本体安装目录(即 $OMF_PATH,默认 ~/.local/share/omf),--config 对应配置目录(即 $OMF_CONFIG,默认 ~/.config/omf)。安装模板 templates/config.fish 展示了这两个变量的写入方式:若设置了 XDG_DATA_HOME 则 OMF_PATH 取 $XDG_DATA_HOME/omf,否则取 $HOME/.local/share/omf;OMF_CONFIG 可在模板中按需取消注释并指定,最后通过 source $OMF_PATH/init.fish 加载框架。

2.4 校验安装脚本完整性

将下载的安装脚本与仓库中的 bin/install.sha256 校验和比对:

curl -sL https://raw.githubusercontent.com/oh-my-fish/oh-my-fish/master/bin/install.sha256 | shasum -a 256 --check

2.5 通过 Git 或离线源码包安装

# with git
$ git clone https://github.com/oh-my-fish/oh-my-fish
$ cd oh-my-fish
$ bin/install --offline
# with a tarball
$ curl https://raw.githubusercontent.com/oh-my-fish/oh-my-fish/master/bin/install > install
$ fish install --offline=omf.tar.gz

运行 install --help 可查看可自定义的全部安装选项。

2.6 升级已有安装

⚠️ 升级前请先备份 dotfiles 及其他敏感数据。

curl -L github.com/oh-my-fish/oh-my-fish/raw/master/bin/install | sh

之后可以安全移除旧的 $fish_path:

rm -rf "$fish_path"

2.7 已知问题

  • 由于 fish 2.6 在某些终端模拟器上存在回归缺陷,右提示符(right prompt)会导致 Shell 无法使用。OMF 的 default 主题自带右提示符,因此在修复发布前需要使用其他主题(见 issue #541)。

2.8 将 Fish 设为默认 Shell(FAQ)

若希望系统默认使用 Fish(见 docs/en-US/FAQ.md),先把 Fish 加入 /etc/shells:

echo "/usr/local/bin/fish" | sudo tee -a /etc/shells

再切换默认 Shell:

chsh -s /usr/local/bin/fish

如需切回(按需替换 /bin/bash 为 /bin/tcsh 或 /bin/zsh):

chsh -s /bin/bash

三、核心命令:omf 使用全览

Oh My Fish 附带一个小巧的实用工具 omf,用于获取和安装新的包与主题。命令分发的入口实现在 pkg/omf/functions/omf.fish:它先解析 -h/--help、-v/--version 等选项,再通过 pkg/omf/functions/core/omf.command.fish 将命令名(含别名)映射到 omf.cli.* 函数并执行。别名映射关系(从源码可见):install/get/i/in → install,list/ls/l → list,remove/rm/r/uninstall → remove,update/up/u → update,search/s → search,theme/t → theme,describe/d → describe,repositories/repo → repositories,new/n → new,channel → channel 等。

3.1 omf update [omf] [<package>...]

更新 Oh My Fish、所有包仓库以及所有已安装的包。

  • 不带参数调用时:更新核心与所有已安装的包;
  • 只更新核心:omf update omf;
  • 选择性更新:只列出需要更新的包名,也可以把 omf 一并列入以同时更新核心。

3.2 omf install [<name>|<url>|<user/repo>]

安装一个或多个包。

  • 直接通过 URL 安装:omf install URL;
  • 通过 GitHub 仓库安装:omf install user/repo;
  • 不带参数调用时:根据 bundle 文件安装缺失的包。

3.3 omf repositories [list|add|remove]

管理用户安装的包仓库(package repositories)。包仓库是 omf install 等命令获取包的来源;默认官方仓库始终已安装并可用。

3.4 omf list

列出已安装的包。

3.5 omf theme <theme>

应用一个主题。直接输入 omf theme 可列出可用主题;安装前可先到 docs/Themes.md 预览主题效果。从 pkg/omf/functions/cli/omf.cli.theme.fish 的源码可以看出:无参数时它会读取 $OMF_CONFIG/theme 文件(不存在则回退为 default),分别以"Installed"和"Available"两组展示已装主题与索引中的可用主题;带一个参数时调用 omf.theme.set 切换主题,若主题未安装则提示先 omf install <name>。

3.6 omf remove <name>

移除一个主题或包。如果包是通过 user/repo 安装的,name 使用 repo 部分即可。

包可以使用卸载钩子(uninstall hooks),卸载时可以完成自定义资源清理,详见 docs/en-US/Packages.md。

3.7 omf reload

通过 exec 用全新 Shell 进程替换当前进程,从而重载 Oh My Fish 与所有插件。

该命令会尽量规避 exec 带来的副作用,并在存在后台进程时阻止重载,做到尽可能安全。

3.8 omf new plugin | theme <name>

生成一个新的插件或主题脚手架。

该命令会在 $OMF_CONFIG/{pkg | themes}/ 下创建带模板的新目录。仓库内对应的模板见 pkg/omf/templates/pkg(插件)与 pkg/omf/templates/themes(主题)。

3.9 omf search -t|--theme / -p|--package <name>

在 Oh My Fish 的数据库中搜索指定的包、主题或两者。支持模糊搜索,例如不确定名字时可以直接 omf search simple。

3.10 omf channel

获取或更改更新通道(update channel)。

默认提供两个通道:stable 通道提供带有最新 tagged 版本的稳定更新;dev 通道提供正在开发中的最新变更。当前设置的通道决定 omf update 会升级到哪个版本。

3.11 omf doctor

在提交 issue 之前用来排查故障。

3.12 omf destroy

卸载 Oh My Fish。

四、进阶:启动机制与 Dotfiles

4.1 启动流程

Oh My Fish 安装器会向 fish 的用户配置文件目录(~/.config/fish/conf.d/)添加一个片段(snippet),该片段会调用 OMF 的启动代码。

注意:该目录中的脚本按文件系统看到的顺序被 source,因此可能需要给脚本文件名加数字前缀来控制顺序。例如:

  • a_script.fish 会比 omf.fish 片段更早执行;如果 a_script.fish 依赖 OMF 管理的插件,建议把脚本改名为 xx_a_script.fish;
  • 想让某个脚本在 omf.fish 之前运行,可以给它加 00_ 前缀;
  • 也可以使用 ~/.config/omf/before.init.fish 来达到同样目的。

每次打开新 Shell 时,启动代码会先初始化 Oh My Fish 的安装路径与配置路径(~/.config/omf,默认),随后 source init.fish 脚本,由它自动加载包、主题以及你的自定义 init 文件。FAQ 中(见 docs/en-US/FAQ.md)将其归纳为:运行 $OMF_CONFIG/before.init.fish(若存在)→ 自动加载 $OMF_PATH/ 下的已装包与主题 → 自动加载配置路径 → 自动加载 $OMF_PATH 与 $OMF_CONFIG 下的 functions 目录 → 运行 $OMF_CONFIG/init.fish(若存在)。

结合 init.fish 源码可以还原完整启动链路:

  1. 若未设置 OMF_CONFIG,则依据 XDG_CONFIG_HOME(默认 $HOME/.config)推导出 OMF_CONFIG 并导出为全局变量(L1-L5);
  2. 若存在 $OMF_CONFIG/before.init.fish 则先 source 它(L7-L8);
  3. 读取当前主题:从 $OMF_CONFIG/theme 读取,文件不存在则回退为 default(L11-L13);
  4. 组装核心函数路径 $OMF_PATH/lib 与 $OMF_PATH/lib/git、主题函数路径,插入 fish_function_path 实现按需自动加载(L15-L21);
  5. 调用 require --path {$OMF_PATH,$OMF_CONFIG}/pkg/* 加载所有包(L24);
  6. 备份原有 fish_user_key_bindings 并重定义之:source $OMF_CONFIG/key_bindings.fish、所有包/主题的 key_bindings.fish,最后调用原始绑定(L27-L47);
  7. 调用 require --no-bundle --path $OMF_CONFIG 加载用户配置(L49);
  8. source 当前主题的 conf.d/*.fish(L52-L55)。

4.2 Dotfiles 目录

$OMF_CONFIG 目录代表 Oh My Fish 的用户状态,非常适合加入 dotfiles 或纳入版本控制。其中有三个重要文件:

  • theme —— 当前主题;
  • bundle —— 当前已安装的包/主题列表;
  • channel —— OMF 获取更新的通道(stable / dev)。

你还可以创建并定制这些特殊文件:

  • init.fish —— Shell 启动后 source 的自定义脚本;
  • before.init.fish —— Shell 启动前 source 的自定义脚本;
  • key_bindings.fish —— 自定义按键绑定,可自由使用 bind 命令。

4.2.1 在 init.fish 中设置变量

init.fish 中最常见的启动命令是变量定义。这类变量通常需要在任何 Shell 会话中都可用,因此应定义为全局变量,例如:

# Golang developers might need this one
set -xg GOPATH $HOME/gocode

# Python developers otherwise
set -xg PYTHONDONTWRITEBYTECODE 1

4.2.2 关于 bundle

每当安装或移除包/主题时,bundle 文件都会被更新。你也可以手动编辑它,然后运行 omf install 使变更生效。请注意:加入 bundle 的包/主题会被自动安装,但从 bundle 中移除的包/主题不会从用户安装中删除。

4.2.3 旧版 fish 的兼容

  • 在 fish 2.2 中没有 conf.d 目录,启动代码必须放在 fish 配置文件(~/.config/fish/config.fish)中;
  • 强烈建议把自定义启动命令放进 init.fish 而不是 ~/.config/fish/config.fish,这样可以让整个 $OMF_CONFIG 目录处于版本控制之下;
  • 如果需要启动命令在 Oh My Fish 开始加载插件之前运行,请放入 before.init.fish;如果不确定,通常放在 init.fish 最好。

五、创建包(Creating Packages)

Oh My Fish 使用一套完善且定义清晰的插件架构来简化插件开发,包括 init/uninstall 钩子、函数与补全的自动加载机制。完整文档见 docs/en-US/Packages.md。下面以创建一个提供 hello_world 命令的包为例。

包名只能包含小写字母和连字符(用于分隔单词)。

5.1 用脚手架生成包结构

使用 omf new 命令生成结构(主题则用 omf new theme my_theme_name):

$ omf new plugin hello_world

该命令会把当前目录切换到新创建的包中,其结构如下:

$ ls -l
  README.md
  init.fish
  functions/hello_world.fish
  completions/hello_world.fish

始终在 README.md 中描述你的包是如何工作的。

建议阅读 fish 的自动补全文档,并在适用时为你的工具提供补全。

functions/hello_world.fish 定义了一个简单函数:

function hello_world -d "Prints hello world"
  echo "Hello World!"
end

包中的每个函数都必须声明在 functions 目录下各自独立的文件中。这是 fish 自动加载机制的要求——它按需加载函数,避免在启动时加载未使用的函数。

命名空间注意事项:fish 没有私有作用域。如果包需要拆分多个函数,请用独特前缀(如包名 hello_world_print_help)避免命名冲突;为不污染命令命名空间,私有函数建议用双下划线前缀(如 __function_name_print_help)。

5.2 钩子(Hooks)体系

Oh My Fish 提供一套 "hooks" 系统,允许为包编写在特定事件发生时运行的脚本,可用于高级安装、自定义资源管理等。钩子就是按触发事件命名、以 init.fish/key_bindings.fish 等特定文件呈现的普通 Fish 脚本,绝大多数钩子位于包项目目录的 hooks 目录中。

启动时触发的钩子(init.fish 与 key_bindings.fish)会拖慢 Shell 启动,务必避免在启动时执行慢代码;如果包不需要某个钩子文件,请删掉它。

钩子执行时的工作目录始终是包的根目录。当前支持的钩子如下:

init

Shell 首次加载时运行一次。脚本位于包的根目录 init.fish。钩子内可访问三个包相关变量:

  • $package:包名
  • $path:包安装路径
  • $dependencies:包依赖

例如 init.fish 内容为:

echo "hello_world initialized"

则首次打开终端时会在顶部看到 hello_world initialized 一行。该钩子适合修改环境、加载资源、自动加载函数等;即使包不导出任何函数,也可以用该事件为包增加功能或动态创建函数。

从 lib/require.fish 源码可以看到 init 钩子背后的加载逻辑:require 会收集 $package_path/functions*、$package_path/completions* 加入 fish_function_path/fish_complete_path(L31-L46),随后逐个 source 包的 init.fish,并注入 $path(包根目录)、$package(包名)变量,同时按 bundle 文件递归 require 依赖(L48-L80)。依赖解析由 lib/require.fish 完成:bundle 中 package <name> 形式的每一行都会被递归加载。此外 init.fish 通过 require --path {$OMF_PATH,$OMF_CONFIG}/pkg/* 完成全部已装包的自动加载。

key_bindings

包或主题需要按键绑定时,应在 key_bindings 钩子中设置。脚本位于包根目录 key_bindings.fish,可在其中自由使用 bind 命令定义自定义按键绑定。

主题同样可以定义按键绑定!切换主题时 Oh My Fish 会重新加载按键绑定。

install

包首次安装时触发。脚本位于 hooks/install.fish。钩子内可访问:

  • $package:包名
  • $path:包安装路径

该钩子适合下载额外资源、设置 Git 子模块、安装 Bash 脚本等第三方依赖。

update

包被更新后触发。脚本位于 hooks/update.fish。钩子内可访问 $package 与 $path,适合更新 Git 子模块或检查第三方依赖的新版本。

uninstall

包通过 omf remove <pkg> 移除前触发。脚本位于 hooks/uninstall.fish。钩子内可访问 $package 与 $path,用于清理自定义资源等。

注:为了向后兼容,位于包根目录的 uninstall.fish 也会被当作卸载钩子运行。钩子也可以通过监听 {$package}_uninstall 或 uninstall_$package 事件来触发。

5.3 公开发布你的包

公开包的官方注册表由 oh-my-fish/packages-main 仓库管理。将包加入官方包数据库的说明见该仓库的 README。

六、附:常用参考速查

事项 仓库位置
框架启动入口 init.fish
自动加载实现(函数/补全路径管理) lib/autoload.fish
包加载与依赖解析 lib/require.fish
omf 命令分发入口 pkg/omf/functions/omf.fish
命令别名映射 pkg/omf/functions/core/omf.command.fish
CLI 子命令实现 pkg/omf/functions/cli
插件/主题脚手架模板 pkg/omf/templates/pkg、pkg/omf/templates/themes
包开发完整文档 docs/en-US/Packages.md
主题画廊(可预览) docs/Themes.md
FAQ(启动细节、默认 Shell 切换等) docs/en-US/FAQ.md
安装模板(OMF_PATH/OMF_CONFIG 变量) templates/config.fish

掌握上述安装流程、omf 子命令、启动顺序与钩子体系后,你就能独立完成"装好框架 → 管理主题/插件 → 用 bundle 版本化配置 → 用钩子开发自己的包"的完整工作流;若对启动细节仍有疑问,可继续阅读 docs/en-US/FAQ.md 中关于 "What does Oh My Fish do exactly" 的说明。

登录后查看全文
oh-my-fish