macOS 安装 oh-my-zsh + 必备插件踩坑记录macOS 安装 oh-my-zsh + 必备插件踩坑记录前

macOS 安装 oh-my-zsh + 必备插件踩坑记录

前言

最近在 Mac 上配置终端环境，安装 zsh-autosuggestions 和 zsh-syntax-highlighting 两个插件时踩了一个隐蔽的坑——git config core.autocrlf=true 导致所有克隆下来的 .zsh 脚本被转成了 Windows 换行符（CRLF），终端疯狂报错 command not found: ^M。

记录一下完整的安装流程和排坑过程，希望能帮到遇到同样问题的朋友。

环境

macOS（Darwin 25.2.0）
Shell：zsh（macOS 默认）
已安装 Git、Homebrew

一、安装 oh-my-zsh

macOS 从 Catalina 起默认 shell 就是 zsh 了，可以直接装 oh-my-zsh：

sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

如果 GitHub 访问慢，可以用镜像：

国内镜像

sh -c "$(curl -fsSL https://gitee.com/mirrors/oh-my-zsh/raw/master/tools/install.sh)"

⚠️ 重要提示：安装完成后，oh-my-zsh 会检测到你已有 ~/.zshrc 文件，并询问是否要用它的模板覆盖：

Found ~/.zshrc. Do you want to replace it with the oh-my-zsh template? [y/N]

请选择 N（直接回车也是 N）！选 y 会用 oh-my-zsh 的默认模板覆盖你现有的 ~/.zshrc，你之前配置的 nvm、环境变量、alias 等全部会丢失。虽然它会备份为 ~/.zshrc.pre-oh-my-zsh，但还是不要给自己找麻烦。

二、安装插件

2.1 zsh-autosuggestions（历史命令补全）

根据你的历史命令，用灰色文字实时提示，按 → 键接受补全。

  git clone --depth=1  <https://github.com/zsh-users/zsh-autosuggestions.git>  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions

2.2 zsh-syntax-highlighting（语法高亮）

命令正确显示绿色，错误显示红色，路径存在会加下划线。

git clone --depth=1  <https://github.com/zsh-users/zsh-syntax-highlighting.git>  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting

2.3 配置 ~/.zshrc

因为上一步选了 N 不覆盖，所以需要手动把 oh-my-zsh 的配置加到现有的 ~/.zshrc 中。

编辑 ~/.zshrc，在文件最前面加上 oh-my-zsh 的核心配置：

oh-my-zsh 配置

export ZSH="$HOME/.oh-my-zsh"

ZSH_THEME="robbyrussell"

plugins=(

git

zsh-autosuggestions

zsh-syntax-highlighting

)

source $ZSH/oh-my-zsh.sh

=== 以下是你原来的配置，保持不动 ===

// 如我电脑的配置：
export NVM_DIR="$HOME/.nvm"

[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

顺序很重要：oh-my-zsh 的配置必须在前面，source $ZSH/oh-my-zsh.sh 之后再放 nvm 等其他配置。

最后生效配置：

source ~/.zshrc

三、自定义主题

oh-my-zsh 内置了 100+ 主题，完整预览可以看官方 Wiki：

👉 oh-my-zsh Themes 主题列表

修改主题只需要改 ~/.zshrc 中的 ZSH_THEME 这一行：

默认主题

ZSH_THEME="robbyrussell"

改成你喜欢的，比如：


ZSH_THEME="agnoster" # 需要安装 Powerline 字体

ZSH_THEME="ys" # 简洁实用，显示完整路径

ZSH_THEME="dst" # 轻量级

ZSH_THEME="fino" # 美观大方

每次随机一个主题（适合选择困难症）

ZSH_THEME="random"

修改后执行 source ~/.zshrc 即可生效。

提示：部分主题（如 agnoster）需要安装 Powerline 字体或 Nerd Font 才能正确显示特殊符号，否则会出现乱码方块。

四、踩坑：`command not found: ^M`

症状

source ~/.zshrc 之后终端刷出一堆报错：

zsh-autosuggestions.zsh:27: command not found: ^M

zsh-autosuggestions.zsh:31: command not found: ^M

zsh-autosuggestions.zsh:154: parse error near `in^M'

zsh-syntax-highlighting.zsh:29: command not found: ^M

原因

^M 就是 \r（回车符）。Windows 的换行是 \r\n（CRLF），而 macOS/Linux 是 \n（LF）。

zsh 会把 \r 当成命令的一部分去执行，自然就 command not found 了。

罪魁祸首：git 全局配置了 core.autocrlf=true。

$ git config --global core.autocrlf

true

这个配置的本意是方便 Windows 用户——克隆时自动把 LF 转成 CRLF。但在 macOS 上，它会把原本正常的 shell 脚本全部搞坏。

解决方案

第一步：修复已有文件

批量把两个插件目录下所有 .zsh 文件的 CRLF 转回 LF：

find ~/.oh-my-zsh/custom/plugins/zsh-autosuggestions -type f -name "*.zsh" \

-exec perl -pi -e 's/\r\n/\n/g' {} +

find ~/.oh-my-zsh/custom/plugins/zsh-syntax-highlighting -type f -name "*.zsh" \

-exec perl -pi -e 's/\r\n/\n/g' {} +

用 file 命令验证：

$ file ~/.oh-my-zsh/custom/plugins/zsh-autosuggestions/zsh-autosuggestions.zsh

正确：ASCII text

错误：ASCII text, with CRLF line terminators

第二步：修改 git 全局配置（治本）

git config --global core.autocrlf input

值	含义	适用系统
`true`	检出时 LF→CRLF，提交时 CRLF→LF	Windows
`input`	检出时不转换，提交时 CRLF→LF	macOS / Linux
`false`	完全不转换	团队统一 LF 时

macOS 用户应该用 input，这样既不会破坏检出的文件，提交时还能自动修正误混入的 CRLF。

第三步：重新打开终端

关掉终端，开一个新的，搞定。

五、效果展示

配置完成后你会得到：

插件	效果
zsh-autosuggestions	输入命令时，基于历史记录灰色提示补全，按 `→` 接受
zsh-syntax-highlighting	正确命令绿色，错误命令红色，有效路径加下划线

总结

安装 oh-my-zsh 时如果已有 ~/.zshrc，选 N 不要覆盖，然后手动添加配置
macOS 上安装插件本身很简单：clone → 改 plugins → source
主题修改只需改 ~/.zshrc 中的 ZSH_THEME，官方主题预览在这里
如果遇到 ^M / command not found 报错，99% 是 CRLF 问题
macOS 用户记得把 git config --global core.autocrlf 设为 input，一劳永逸

macOS 安装 oh-my-zsh + 必备插件踩坑记录