Oh My Zsh 更新失败：第三方插件安装目录冲突及解决方案

最近在更新 Oh My Zsh 时，遇到了一个 Git 文件冲突问题。排查后发现，我之前编写的 Zsh 自动安装脚本将第三方插件直接安装到了 Oh My Zsh 的内置插件目录。

本文记录问题现象、排查思路、解决方法，以及如何调整安装脚本，避免以后再次出现类似问题。

一、问题现象

执行以下命令更新 Oh My Zsh：

1
omz update

终端提示：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
Updating Oh My Zsh
error: The following untracked working tree files
would be overwritten by merge:

    plugins/zsh-autosuggestions/LICENSE
    plugins/zsh-autosuggestions/README.md
    plugins/zsh-autosuggestions/src/async.zsh
    plugins/zsh-syntax-highlighting/README.md
    plugins/zsh-syntax-highlighting/highlighters/README.md
    ...

Please move or remove them before you merge.
Aborting
There was an error updating. Try again later?

从报错信息可以看出，冲突主要涉及两个插件：

  • zsh-autosuggestions：根据历史命令提供自动补全建议。
  • zsh-syntax-highlighting：为 Zsh 命令提供实时语法高亮。

Git 检测到本地存在未跟踪的文件，而本次更新准备写入相同路径。为了避免覆盖本地文件，Git 中止了更新。

二、问题原因

检查之前编写的 Zsh 自动安装脚本，发现第三方插件使用了以下安装方式：

1
2
3
4
5
6
7
git clone \
  https://github.com/zsh-users/zsh-syntax-highlighting.git \
  ~/.oh-my-zsh/plugins/zsh-syntax-highlighting

git clone \
  https://github.com/zsh-users/zsh-autosuggestions.git \
  ~/.oh-my-zsh/plugins/zsh-autosuggestions

问题就在于安装路径。

Oh My Zsh 提供了两个不同的插件目录：

1
2
3
4
5
6
~/.oh-my-zsh/
├── plugins/
│   └── ...
└── custom/
    └── plugins/
        └── ...

其中：

  • plugins/：由 Oh My Zsh 自身管理的插件目录。
  • custom/plugins/：用于安装用户自己的第三方插件。

之前的安装脚本直接将第三方插件克隆到了 plugins/ 目录。

这样做可能暂时不影响插件的正常使用，但会增加后续更新时发生 Git 文件冲突的风险。

需要说明的是，Git 报错能够证明本地未跟踪文件与本次更新的目标文件存在路径冲突，但仅凭这条报错，无法确定上游具体在哪个版本引入了相关文件。

三、解决方案

我的处理思路是删除旧位置的第三方插件，将它们重新安装到正确的目录，然后更新 Oh My Zsh。

1. 删除旧插件

首先确认 Oh My Zsh 的实际安装目录：

1
echo "$ZSH"

如果使用默认安装路径，可以检查：

1
2
ls -la ~/.oh-my-zsh/plugins/zsh-autosuggestions
ls -la ~/.oh-my-zsh/plugins/zsh-syntax-highlighting

确认这两个目录确实是此前手动克隆的第三方插件，并且没有需要保留的自定义修改后，执行：

1
2
3
rm -rf -- \
  ~/.oh-my-zsh/plugins/zsh-autosuggestions \
  ~/.oh-my-zsh/plugins/zsh-syntax-highlighting

注意：如果当前版本的 Oh My Zsh 已经将这些目录纳入 Git 管理，就不要直接删除。应先通过 git status 和 git ls-files 确认文件归属。

2. 更新 Oh My Zsh

清理冲突文件后，重新执行：

1
omz update

如果没有其他冲突，Git 应该能够继续执行更新。

3. 重新安装第三方插件

先创建第三方插件目录：

1
mkdir -p ~/.oh-my-zsh/custom/plugins

安装 zsh-autosuggestions：

1
2
3
git clone \
  https://github.com/zsh-users/zsh-autosuggestions.git \
  ~/.oh-my-zsh/custom/plugins/zsh-autosuggestions

安装 zsh-syntax-highlighting：

1
2
3
git clone \
  https://github.com/zsh-users/zsh-syntax-highlighting.git \
  ~/.oh-my-zsh/custom/plugins/zsh-syntax-highlighting

如果目标目录已经存在同名插件，需要先检查，避免重复克隆。

4. 检查 Zsh 配置

打开 ~/.zshrc：

1
vim ~/.zshrc

确保插件配置包含：

1
2
3
4
5
plugins=(
  git
  zsh-autosuggestions
  zsh-syntax-highlighting
)

建议将 zsh-syntax-highlighting 放在插件列表的最后。

需要注意，虽然第三方插件的实际安装位置发生了变化，但 .zshrc 中仍然使用插件名称，不需要填写插件的完整路径。

最后重新启动 Zsh：

1
exec zsh

检查自动补全建议和语法高亮是否正常工作。

四、修正自动安装脚本

我之前的自动安装脚本存在一个设计问题：将第三方插件直接克隆到 Oh My Zsh 自身管理的目录。

因此，只需要将原来的两条 Git Clone 命令修改为：

1
2
3
4
5
6
7
git clone \
  https://github.com/zsh-users/zsh-syntax-highlighting.git \
  ~/.oh-my-zsh/custom/plugins/zsh-syntax-highlighting

git clone \
  https://github.com/zsh-users/zsh-autosuggestions.git \
  ~/.oh-my-zsh/custom/plugins/zsh-autosuggestions

对于已经安装过插件的机器，建议在脚本中增加目录检查，避免重复执行时出现错误。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
PLUGIN_DIR="$HOME/.oh-my-zsh/custom/plugins"

mkdir -p "$PLUGIN_DIR"

if [ ! -e "$PLUGIN_DIR/zsh-autosuggestions" ]; then
  git clone \
    https://github.com/zsh-users/zsh-autosuggestions.git \
    "$PLUGIN_DIR/zsh-autosuggestions"
fi

if [ ! -e "$PLUGIN_DIR/zsh-syntax-highlighting" ]; then
  git clone \
    https://github.com/zsh-users/zsh-syntax-highlighting.git \
    "$PLUGIN_DIR/zsh-syntax-highlighting"
fi

这个版本适合新安装或已经完成旧目录清理的环境。如果插件目录已经存在，脚本会跳过安装，不会自动更新已有插件。

五、总结

这次遇到的问题，本质上是 Git 在更新过程中发现目标路径存在未跟踪文件，为保护本地数据而主动终止了合并。

对于 Oh My Zsh，建议遵循以下原则：

  1. 将第三方插件安装到 custom/plugins/ 目录。
  2. 不要随意修改 Oh My Zsh 自身管理的文件。
  3. 更新失败时，先检查 Git 状态，不要直接使用 git reset --hard 或 git clean -fd。
  4. 自动安装脚本应该支持重复执行，并在删除文件前确认文件归属。

通过将第三方插件与 Oh My Zsh 自身管理的文件分开，可以降低后续升级时出现冲突的风险。

参考资料