macOS 现代 Zsh 终端配置方案
推荐组合：原生 Zsh + zsh-autosuggestions + zsh-syntax-highlighting + Starship
这套方案不依赖 Oh My Zsh，配置更轻量、启动更快，也更容易排查问题。
一、方案组成
| 组件 | 作用 |
|---|---|
| Zsh | macOS 默认 Shell |
| zsh-autosuggestions | 根据历史命令显示灰色提示 |
| zsh-syntax-highlighting | 对合法、错误命令进行语法高亮 |
| Starship | 美化终端提示符 |
不建议同时安装 zsh-autocomplete 和 zsh-autosuggestions，两者功能存在重叠，也可能干扰补全行为。
二、安装组件
确认 Homebrew 已安装：
brew --version
安装所需组件：
brew install zsh-autosuggestions zsh-syntax-highlighting starship
三、备份现有配置
执行：
cp ~/.zshrc ~/.zshrc.backup
如果后续配置出现问题，可以恢复：
cp ~/.zshrc.backup ~/.zshrc
exec zsh
四、配置 .zshrc
编辑配置文件：
nano ~/.zshrc
建议使用以下完整配置：
# ==================================================
# Homebrew
# Apple Silicon Mac 使用 /opt/homebrew
# Intel Mac 使用 /usr/local
# ==================================================
if [[ -x /opt/homebrew/bin/brew ]]; then
eval "$(/opt/homebrew/bin/brew shellenv)"
elif [[ -x /usr/local/bin/brew ]]; then
eval "$(/usr/local/bin/brew shellenv)"
fi
# ==================================================
# 历史记录
# ==================================================
HISTFILE="$HOME/.zsh_history"
HISTSIZE=50000
SAVEHIST=50000
# 多个终端共享历史记录
setopt SHARE_HISTORY
# 追加写入历史文件
setopt APPEND_HISTORY
setopt INC_APPEND_HISTORY
# 忽略连续重复命令
setopt HIST_IGNORE_DUPS
# 删除历史中的旧重复命令
setopt HIST_IGNORE_ALL_DUPS
# 忽略命令前后多余空格
setopt HIST_REDUCE_BLANKS
# ==================================================
# Zsh 自动补全
# ==================================================
autoload -Uz compinit
compinit
# 补全菜单
zstyle ':completion:*' menu select
# 补全时忽略大小写
zstyle ':completion:*' matcher-list 'm:{a-zA-Z}={A-Za-z}'
# ==================================================
# 历史命令自动提示
# ==================================================
# 灰色提示颜色
ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE='fg=8'
source "$(brew --prefix)/share/zsh-autosuggestions/zsh-autosuggestions.zsh"
# Ctrl + F：按单词接受提示
bindkey '^F' forward-word
# ==================================================
# Starship 提示符
# ==================================================
eval "$(starship init zsh)"
# ==================================================
# 命令语法高亮
# 必须尽量放在配置文件最后
# ==================================================
source "$(brew --prefix)/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh"
保存方法：
- 按
Control + O - 按回车确认文件名
- 按
Control + X退出
让配置立即生效：
exec zsh
也可以执行：
source ~/.zshrc
通常更推荐使用 exec zsh，它会重新启动当前 Zsh 会话。
五、历史记录提示怎么使用
先执行过一条命令，例如：
cd ~/Documents
下一次输入：
cd
终端会在后面显示灰色建议，例如：
cd ~/Documents
其中未输入的部分会显示为灰色。
常用快捷键
| 操作 | 快捷键 |
|---|---|
| 接受整条灰色提示 | → 右方向键 |
| 接受下一个单词 | Ctrl + F |
| 执行当前命令 | Enter |
| 搜索历史命令 | Ctrl + R |
| 查看上一条历史命令 | ↑ |
| 查看下一条历史命令 | ↓ |
| 清空当前输入 | Ctrl + U |
| 移动到行首 | Ctrl + A |
| 移动到行尾 | Ctrl + E |
六、使用 Ctrl + R 搜索历史命令
按：
Ctrl + R
然后输入关键字，例如：
docker
终端会搜索以前执行过的包含 docker 的命令。
继续按 Ctrl + R，可以向前查找更多匹配记录。
找到目标命令后：
- 按
Enter：直接执行 - 按右方向键：先放到命令行中再编辑
- 按
Ctrl + G：取消搜索
七、Starship 提示符配置
Starship 默认配置通常比较简洁，有时进入终端后只会显示一个 > 或 ➜。
可以将提示符配置为：
用户名@电脑名 当前目录 Git分支 ➜
例如：
david@Mac-mini ~/Projects/my-app git:main ➜
1. 创建配置文件
mkdir -p ~/.config
touch ~/.config/starship.toml
使用 nano 编辑：
nano ~/.config/starship.toml
2. 推荐配置
将下面内容复制到 ~/.config/starship.toml：
"$schema" = "https://starship.rs/config-schema.json"
add_newline = false
format = """
$username\
$hostname\
$directory\
$git_branch\
$git_status\
$character"""
# 用户名
[username]
show_always = true
style_user = "bold blue"
style_root = "bold red"
format = "[$user]($style)"
# 电脑名称
[hostname]
ssh_only = false
style = "bold green"
format = "[@$hostname]($style) "
# 当前目录
[directory]
style = "bold cyan"
format = "[$path]($style) "
truncation_length = 4
truncate_to_repo = false
# Git 分支
[git_branch]
symbol = "git:"
style = "bold purple"
format = "[$symbol$branch]($style) "
# Git 状态
[git_status]
style = "bold red"
format = "[$all_status$ahead_behind]($style) "
# 命令提示符
[character]
success_symbol = "[➜](bold green)"
error_symbol = "[➜](bold red)"
保存并退出 nano：
- 按
Control + O - 按回车确认文件名
- 按
Control + X退出
让配置立即生效：
exec zsh
3. 只显示用户名和目录
如果不希望显示电脑名，可以把 format 中的 $hostname\ 删除：
format = """
$username\
$directory\
$git_branch\
$git_status\
$character"""
效果类似：
david ~/Projects/my-app git:main ➜
4. 只显示目录和 Git 信息
如果希望更加简洁，可以不显示用户名和电脑名：
format = """
$directory\
$git_branch\
$git_status\
$character"""
效果类似：
~/Projects/my-app git:main ➜
5. 注意 > 的两种情况
如果终端可以正常输入和执行命令，单独显示 > 通常只是 Starship 提示符配置比较简单。
如果输入命令后一直无法执行，并再次出现 >，可能是上一条命令中的引号、括号或反引号没有闭合。此时按：
Ctrl + C
即可取消当前未完成的命令。
八、验证安装结果
执行：
brew list | grep -E 'zsh-autosuggestions|zsh-syntax-highlighting|starship'
应该看到：
starship
zsh-autosuggestions
zsh-syntax-highlighting
检查 Starship：
starship --version
检查当前 Shell：
echo $SHELL
macOS 默认通常为：
/bin/zsh
九、常见问题
1. 看不到灰色历史提示
先确认历史文件中有内容：
tail ~/.zsh_history
手动加载插件测试：
source "$(brew --prefix)/share/zsh-autosuggestions/zsh-autosuggestions.zsh"
然后输入以前执行过的命令前几个字符。
检查 .zshrc 是否存在：
source "$(brew --prefix)/share/zsh-autosuggestions/zsh-autosuggestions.zsh"
2. 提示颜色太淡
把下面配置放在加载插件之前：
ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE='fg=8'
也可以尝试：
ZSH_AUTOSUGGEST_HIGHLIGHT_STYLE='fg=244'
3. 出现 command not found: brew
Apple Silicon Mac 执行：
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
Intel Mac 执行：
echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/usr/local/bin/brew shellenv)"
4. 修改配置后终端报错
使用 Zsh 检查配置语法：
zsh -n ~/.zshrc
如果没有任何输出，说明没有明显语法错误。
查看具体错误：
source ~/.zshrc
临时恢复备份：
cp ~/.zshrc.backup ~/.zshrc
exec zsh
5. 语法高亮没有生效
zsh-syntax-highlighting 应尽量放在 .zshrc 最后：
source "$(brew --prefix)/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh"
它后面不要再加载其他会修改 Zsh 行编辑器的插件。
6. Starship 没有生效
确认 .zshrc 中存在：
eval "$(starship init zsh)"
然后执行：
exec zsh
十、升级组件
统一升级：
brew update
brew upgrade
只升级这几个组件：
brew upgrade zsh-autosuggestions zsh-syntax-highlighting starship
十一、卸载组件
brew uninstall zsh-autosuggestions zsh-syntax-highlighting starship
然后从 ~/.zshrc 中删除对应的 source 和 Starship 初始化配置。
十二、最终推荐
推荐保持以下结构：
Zsh
├── zsh-autosuggestions
├── zsh-syntax-highlighting
└── Starship
相比 Oh My Zsh，这套方案具有以下特点：
- 加载内容更少
- 启动速度更快
- 配置透明
- 插件冲突更少
- Homebrew 统一管理
- 更适合开发环境长期使用
对于日常 Java、Node.js、Git、Docker、Python 和 macOS 开发，这套配置已经足够完整。