# macOS 终端现代化环境档案

> source: 想法/草稿/macOS终端现代化环境档案.md

> AI 整理。记录这台 Mac 的终端环境是怎么配出来的，以后换机器、加工具、回滚时往这里继续积攒。

# macOS 终端现代化环境档案

> 适用机器：kiharari 的 MacBook Pro（Apple Silicon M1 Pro · macOS 27 · zsh + Oh My Zsh + powerlevel10k）
> 终端：Ghostty 1.3.1 · 编辑器：VS Code
> 最后整理：本会话结束（含 CLI 工具、zsh、终端模拟器、VS Code、tmux 全部配置）

---

## 一、总览：这次现代化了什么

| 层 | 工具/文件 | 做了什么 |
|---|---|---|
| CLI 命令 | eza/bat/fd/rg/fzf/zoxide/dust/ncdu/btop | 替换系统旧命令，更好看更快 |
| Shell | `~/.zshrc` | PATH、别名、历史、编辑器、懒加载等全面升级 |
| 终端模拟器 | Ghostty `~/.config/ghostty/config` | Nerd Font 图标、Catppuccin 主题、现代化外观 |
| 编辑器 | VS Code `settings.json` | 终端/编辑器统一 Nerd Font |
| 复用器 | tmux 3.7c + `~/.tmux.conf` | 会话保持、分屏、主题状态栏、自动恢复 |

---

## 二、现代 CLI 工具

### 对照表

| 原命令 | 现命令 | 状态 | 说明 |
|---|---|---|---|
| `ls` | `eza` | ✅ 别名 | 图标+Git 状态+目录优先；`ll`/`lt`(树) 也有 |
| `cat` | `bat` | ✅ 别名 | 语法高亮+行号 |
| `grep` | `rg` | ✅ 别名⚠️ | 默认递归、忽略 .gitignore |
| `find` | `fd` | ✅ 别名⚠️ | 语法直观 |
| 历史/文件搜 | `fzf` | ✅ | Ctrl-R / Ctrl-T / Tab 补全 |
| `cd` | zoxide 接管 | ✅ | 输部分路径即跳；`cdi` 交互选 |
| `du` | `dust` / `ncdu` | ✅ 安装 | 可视化磁盘占用 |
| `top` | `btop` | ✅ 别名 | 图形监控 |
| `man` | `tldr` | ✅ 已有 | 精简示例 |

### 安装命令（本机必须用原生 brew）

```bash
/opt/homebrew/bin/brew install eza bat fd ripgrep fzf zoxide dust ncdu btop tmux
```

⚠️ **本机 Homebrew 有 Rosetta(/usr/local) 和原生(/opt/homebrew) 两套**。Rosetta 版报 Xcode 旧无法安装，一律用 `/opt/homebrew/bin/brew`；现在 `brew` 命令本身也已默认指向原生版。

### 兼容性注意

- `rg` 无 `-r`(默认已递归)、正则用 `-e` 而非 `-E`；`fd` 参数是 `fd [模式] [路径]`
- 想用原版命令：`\grep` / `\find` / `command grep`（别名只影响交互式输入，不影响脚本）
- zoxide 匹配是「连续子串」(忽略大小写)：`cd Downlo` ✅ 能跳，`cd Downlods`(漏字母) ❌；真打错用 `cdi`(fzf 模糊)
- `cat` 输出到管道/脚本时 bat 自动去色，安全

---

## 三、`~/.zshrc`（最终有效配置）

### plugins（OMZ）

```zsh
plugins=(
  git
  zsh-autosuggestions
  zsh-syntax-highlighting
  extract        # z 旧插件已移除，由 zoxide 取代
)
zstyle ':omz:update' mode auto        # OMZ 静默自动更新
```

### 现代 CLI / PATH / 工具集成块

```zsh
# Apple Silicon 原生 Homebrew（官方 shellenv，替代手写 PATH）
if [ -x /opt/homebrew/bin/brew ]; then eval "$(/opt/homebrew/bin/brew shellenv)"; fi

if command -v eza >/dev/null 2>&1; then
  alias ls='eza --git --group-directories-first --icons=auto'
  alias ll='eza -la --git --group-directories-first --icons=auto'
  alias lt='eza --tree --level=3 --git --group-directories-first --icons=auto'
fi
if command -v bat  >/dev/null 2>&1; then alias cat='bat';  fi
if command -v rg   >/dev/null 2>&1; then alias grep='rg';  fi   # 原版用 \grep
if command -v fd   >/dev/null 2>&1; then alias find='fd';  fi   # 原版用 \find
if command -v btop >/dev/null 2>&1; then alias top='btop'; fi
# cd/cdi：zoxide 接管 cd（--cmd cd 模式下 z/zi 变为 cd/cdi）
if command -v zoxide >/dev/null 2>&1; then eval "$(zoxide init zsh --cmd cd)"; fi
# fzf：Ctrl-R 历史 / Ctrl-T 文件 / Tab 补全
if command -v fzf >/dev/null 2>&1; then source <(fzf --zsh); fi
```

### 编辑器 / 历史 / shell 细节

```zsh
# nvm 懒加载：首次用到才加载（加速启动）
export NVM_DIR="$HOME/.nvm"
if [ -s "$NVM_DIR/nvm.sh" ]; then
  nvm() {
    unset -f nvm
    \. "$NVM_DIR/nvm.sh"
    [ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"
    nvm "$@"
  }
fi

# 默认编辑器（git commit 等会用到）
if command -v nvim >/dev/null 2>&1; then export EDITOR=nvim VISUAL=nvim
elif command -v code >/dev/null 2>&1; then export EDITOR='code --wait' VISUAL='code --wait'; fi

# 历史：更大 + 去重（fzf Ctrl-R 受益）
HISTSIZE=100000; SAVEHIST=100000
setopt hist_ignore_all_dups hist_find_no_dups hist_reduce_blanks
setopt NO_BEEP interactive_comments     # 去响铃 / 命令行可写 # 注释
unsetopt autocd                          # 与 zoxide 的 cd 冲突，关闭

# 只在登录 shell 显示 fastfetch（新标签不再整屏刷）
if [[ -o login ]] && [[ -o interactive ]] && command -v fastfetch >/dev/null 2>&1; then
  fastfetch
fi
```

> 原有保留：p10k instant prompt（文件顶部）、conda PATH 注入（顶部）、`pi-usage()` 函数（底部）。
> 补全缓存：给新装工具装好补全后，如 Tab 不认，执行 `rm -f ~/.zcompdump*` 后重开 shell。

---

## 四、终端模拟器：Ghostty（`~/.config/ghostty/config`）

```ini
# Ghostty 1.3.1 · macOS
font-family = "CaskaydiaCove Nerd Font Mono"   # ← 图标显示的关键
font-size = 13
theme = "Catppuccin Mocha"
background-opacity = 0.93
background-blur-radius = 25
window-padding-x = 12
window-padding-y = 12
macos-titlebar-style = transparent
window-save-state = always
shell-integration = zsh
cursor-style = block
cursor-style-blink = true
copy-on-select = true
mouse-hide-while-typing = true
confirm-close-surface = false
scrollback-limit = 50000
```

改动即热重载；新开窗口生效。验证命令：

```bash
/Applications/Ghostty.app/Contents/MacOS/ghostty +show-config   # 应无 error
/Applications/Ghostty.app/Contents/MacOS/ghostty +list-themes   # 内置主题列表
```

---

## 五、VS Code（`~/Library/Application Support/Code/User/settings.json`）

改动两处（其余保留）：

```jsonc
"editor.fontFamily": "CaskaydiaCove Nerd Font Mono",      // 原来是无效的 "Fira"
"terminal.integrated.fontFamily": "CaskaydiaCove Nerd Font Mono",  // 原来是 "monospace"
```

---

## 六、tmux（tmux 3.7c，`~/.tmux.conf`）

旧配置（shell 脚本 powerline，已过时）备份于 `~/.tmux.conf.bak-2024`。旧文件引用的 `~/.config/tmux/` 已不再需要。

### 配置全文

```tmux
set -g default-terminal "tmux-256color"
set -ag terminal-features ",*:RGB"     # 真彩色
set -g set-clipboard on
set -g escape-time 10
set -g history-limit 20000
set -g focus-events on
set -g mouse on
set -g renumber-windows on
set -g base-index 1
setw -g pane-base-index 1
setw -g mode-keys vi

# 前缀键 Ctrl+a（连按两次输入字面 ^a）
set -g prefix C-a
unbind C-b
bind C-a send-prefix

# 窗口/窗格：默认开在当前目录
bind c new-window -c "#{pane_current_path}"
bind | split-window -h -c "#{pane_current_path}"   # 左右分屏
bind - split-window -v -c "#{pane_current_path}"   # 上下分屏
unbind '"'
unbind %
bind x kill-pane
bind n next-window
bind p previous-window
bind , rename-window
bind r source-file ~/.tmux.conf \; display "tmux reloaded ✓"

# vim 键位切窗格 / 微调大小
bind h select-pane -L
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R
bind -r H resize-pane -L 5
bind -r J resize-pane -D 5
bind -r K resize-pane -U 5
bind -r L resize-pane -R 5

# 复制模式（vi）
bind [ copy-mode
bind -T copy-mode-vi v send-keys -X begin-selection
bind -T copy-mode-vi V send-keys -X select-line
bind -T copy-mode-vi r send-keys -X rectangle-toggle
bind -T copy-mode-vi Escape send-keys -X cancel
bind -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "pbcopy"
bind -T copy-mode-vi Enter send-keys -X copy-pipe-and-cancel "pbcopy"

# 外观（Catppuccin Mocha 色板，与 Ghostty 同源）
set -g status-interval 5
set -g status-style "bg=default,fg=#cdd6f4"
set -g message-style "bg=#313244,fg=#cdd6f4"
set -g pane-border-style "fg=#313244"
set -g pane-active-border-style "fg=#89b4fa"
set -g status-left "#[bg=#89b4fa,fg=#1e1e2e,bold]  #S  #[bg=default,fg=#89b4fa]"
set -g status-left-length 40
setw -g window-status-current-format "#[bg=#313244,fg=#cdd6f4,bold] #I:#W #[bg=default,fg=#313244]"
setw -g window-status-format "#[fg=#585b70] #I:#W "
set -g window-status-separator ""
set -g status-right "#[fg=#a6adc8] %H:%M #[fg=#585b70]%d %b "
set -g status-right-length 60

# 插件（TPM）
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-sensible'
set -g @plugin 'tmux-plugins/tmux-yank'
set -g @plugin 'tmux-plugins/tmux-resurrect'
set -g @plugin 'tmux-plugins/tmux-continuum'
set -g @continuum-restore 'on'          # 启动自动恢复上次会话
set -g @continuum-save-interval '15'    # 每 15 分钟自动快照
set -g @resurrect-capture-pane-contents 'on'

if "test -d ~/.tmux/plugins/tpm" "run-shell ~/.tmux/plugins/tpm/tpm"
```

### 新手心法

三个层级：**Session 会话(一个工作现场) → Window 窗口(标签页) → Pane 窗格(分屏)**。

日常三连（90% 的日常）：

| 命令 | 作用 |
|---|---|
| `tmux` | 进入 tmux |
| `Ctrl+a` `d` | 脱离：程序继续跑，回到普通终端 |
| `tmux attach` | 接回上次会话，一切原样 |

窗口：`Ctrl+a` `c` 新建 / `n` `p` 切换 / `,` 改名
分屏：`Ctrl+a` `|` 左右 / `-` 上下 / `h j k l` 移动 / `x` 关闭
滚动：鼠标直接滚（看历史）；复制：选中即进剪贴板
全部快捷键：`Ctrl+a` `?`（q 退出）

---

## 七、图标（Nerd Font）支持链路

终端里显示图标需三步齐全：

```
1. 装 Nerd Font        → CaskaydiaCove Nerd Font（已装 ~/Library/Fonts，三种变体）
2. 终端用该字体        → Ghostty font-family = "CaskaydiaCove Nerd Font Mono" ✅
3. 命令输出图标        → eza --icons=auto、p10k、fzf 等（已配）✅
```

> 中文字符由系统字体自动回退渲染，无需配置。VS Code 同理。

---

## 八、一条命令验证全部

```bash
alias ls ll cat grep find top                    # 应显示各别名
which brew eza bat rg fd btop tmux               # 应都在 /opt/homebrew/bin
zsh -ic 'whence -w cd cdi; bindkey | grep fzf'   # zoxide/fzf 集成
tmux -L check new-session -d -s t && tmux -L check kill-server   # tmux 配置无错
/Applications/Ghostty.app/Contents/MacOS/ghostty +show-config     # ghostty 无错
```

---

## 九、回滚 / 备份位置

| 文件 | 备份 |
|---|---|
| `~/.zshrc` | 改动前无独立备份（git 化 ~/dotfiles 是后续建议） |
| `~/.tmux.conf` | `~/.tmux.conf.bak-2024` |
| VS Code settings.json | 仅改 2 行字体，可手改回 |
| Ghostty config | 原无配置文件（全默认），删除即还原 |

卸载工具：`/opt/homebrew/bin/brew uninstall eza bat fd ripgrep fzf zoxide dust ncdu btop tmux`

---

## 十、遗留说明 & 后续可扩展

- **双 Homebrew**（/usr/local Rosetta + /opt/homebrew 原生）：默认已用原生；/usr/local 残留包（如 git）暂不动，别用 Rosetta brew 装新东西
- **nvm 与 brew node 并存**：默认 `node` 是 brew 版(22.22.1)，nvm 管理 22.22.2；`nvm ls` 正常，如需理顺可后续处理
- p10k 在非终端环境偶报 `gitstatus failed`，属正常终端无关现象；若正常终端也出现再排查
- 可扩展：lazygit/delta（git 交互）、vivid(LS_COLORS 分色)、tmux 状态栏加 CPU/网络、`~/dotfiles` git 仓库托管全部配置
