作用</th>	可能出现的命令</th>	常见软件包名</th></tr></thead>
模糊搜索</td>	`fzf</code></td>`	`fzf</code></td></tr>`
文本搜索</td>	`rg</code></td>`	`ripgrep</code></td></tr>`
文件查找</td>	`fd</code> / fdfind</code></td>`	`fd</code> / fd-find</code></td></tr>`
目录列表</td>	`eza</code> / exa</code></td>`	`eza</code></td></tr>`
文件查看</td>	`bat</code> / batcat</code></td>`	`bat</code></td></tr>`
系统监控</td>	`btop</code></td>`	`btop</code></td></tr>`
Git 终端界面</td>	`lazygit</code></td>`	`lazygit</code></td></tr>`
命令示例</td>	`tldr</code></td>`	tealdeer</code></td></tr> </tbody></table> 工具集是普通安装的默认内容，不需要逐项选择。只有想要更轻量的安装时，才使用：</p> ./install.sh</span> --minimal</span></span></code></pre> 它会跳过默认工具集，但仍然尝试安装基础依赖。工具集中的单个软件包在某个发行版中不存在时，只会发出警告并继续；基础 shell 仍能工作。zsh</code>、git</code> 或 curl</code> 这类必需命令在安装后仍缺失，则安装会停止。</p> 安装器目前会识别 Homebrew、apt、dnf、yum、pacman、apk 和 zypper。macOS 没有 Homebrew 时不会静默安装 Homebrew；Cygwin 的系统包则需要通过 Cygwin 安装器维护。</p> </i></a> 它如何避免破坏已有配置</h2> 这是这个项目最重要的设计取舍：共享配置不能以“把用户的 .zshrc</code> 换成我的版本”为代价。</p> 安装器不会把仓库中的 home/.zshrc</code> 直接复制覆盖用户文件，而是在用户的 ~/.zshrc</code> 和 ~/.zprofile</code> 末尾维护一个可重复更新的区块：</p> # >>> zsh-dotfiles managed block >>></span></span> ...</span></span> # <<< zsh-dotfiles managed block <<<</span></span></code></pre> 虽然仓库已经从 zsh-dotfiles</code> 改名为 canxin-zsh</code>，marker 仍然保留旧名称，这是为了让历史安装可以被新版本识别和更新，避免升级后加载两遍配置。</p> </i></a> 新配置和已有配置的区别</h3> 空配置会进入 bootstrap 模式，启用完整的默认历史、补全、目录导航、快捷键、Oh My Zsh 和主题；</li> 非空配置会进入兼容集成模式，保留用户已有的主题、插件、历史选项、补全样式和快捷键；</li> 已经加载 Oh My Zsh 时不会重复加载，也不会重设用户的 ZSH_THEME</code> 和 plugins</code>；</li> 检测到 zinit、zplug、zgen、antigen、zimfw、sheldon、prezto、zcomet 等其他框架时，不会再额外启动 Oh My Zsh；</li> 已有 alias、function 和可读的 Powerlevel10k 配置会优先保留；</li> 普通 symlink 会保留，安装器会更新它指向的目标；如果 symlink 直接指向仓库 source 文件，会先安全解除这个自引用关系，避免递归加载。</li> </ul> 如果安装器确实需要修改已有配置，会先在下面的位置创建备份：</p> ~/.config/zsh-dotfiles/backups/</span></span></code></pre> 机器特定的设置可以放在：</p> ~/.zprofile.local # PATH、SDK、代理和登录 shell 设置</span></span> ~/.zshrc.local # 本机 alias、函数和交互式设置</span></span></code></pre> 这些文件不会被仓库覆盖，也不应该提交到公开仓库。对于空配置，它们会自动加载；对于已有非空配置，安装器默认不额外插入加载语句，以免改变原来的加载顺序，可以由用户自行 source。</p> </i></a> 安装后如何检查和更新</h2> 本地 clone 的项目可以运行：</p> bin/zsh-doctor</span></span></code></pre> 远程安装默认把 source checkout 放在：</p> ${XDG_DATA_HOME:-$HOME/.local/share}/canxin-zsh</span></span></code></pre> 因此也可以直接执行：</p> "</span>${</span>XDG_DATA_HOME</span>:-</span>$HOME</span>/</span>.local</span>/</span>share</span>}</span>/canxin-zsh/bin/zsh-doctor"</span></span></code></pre> 诊断工具会检查 zsh、Git、默认工具集以及 code</code> 命令是否存在，方便判断某个 alias 或增强功能为什么没有启用。</p> 配置加载后，可以使用：</p> zupdate-all</span></span></code></pre> 它会尝试更新 Oh My Zsh 和 $ZSH_CUSTOM</code> 下的 Git 插件/主题 checkout。如果 $ZSH_CUSTOM</code> 里还有用户自己放入的 Git checkout，它们也可能被更新；如果系统有 Homebrew，还会执行 brew update</code> 和 brew upgrade</code>。因此这个命令适合明确希望更新整套开发环境时使用。</p> 安装阶段的更新选项则更细分：</p> ./install.sh</span> --update</span> # 更新远程地址匹配的依赖 checkout</span></span> ./install.sh</span> --update-source</span> # 更新远程安装管理的 canxin-zsh source checkout</span></span> ./install.sh</span> --dry-run</span> # 在本地 checkout 中只查看计划，不写配置</span></span></code></pre></i></a> 支持的平台</h2> 项目会根据环境使用对应的系统包管理器：</p> macOS：优先使用已经安装的 Homebrew，也可以使用系统已有的 zsh 和 curl；</li> Debian、Ubuntu、WSL：使用 apt-get</code>；</li> Fedora、RHEL：使用 dnf</code> 或 yum</code>；</li> Arch Linux 和 MSYS2：使用 pacman</code>；</li> Alpine Linux：使用 apk</code>；</li> openSUSE：使用 zypper</code>；</li> Cygwin：先用 Cygwin 安装器准备 git</code>、curl</code> 和 zsh</code>，再运行项目安装器。</li> </ul> 原生 Windows PowerShell 和单独的 Git Bash 都不是 zsh 运行环境。Windows 用户应把 WSL 作为首选，或者使用已经安装 zsh 的 MSYS2/Cygwin。</p> </i></a> 这个项目为什么值得单独做一个安装器</h2> 如果只是把几个配置文件放进 Git 仓库，跨平台时很快就会遇到这些问题：</p> macOS、Linux 和 MSYS2 的包管理器完全不同；</li> fd</code>、bat</code> 等工具在 Debian 系统上的命令名可能与 macOS 不同；</li> 有些机器已经有自己的 Oh My Zsh 或其他框架；</li> 用户的 .zshrc</code> 里可能已经有大量 alias、函数和本机变量；</li> 通过 curl \| bash</code> 安装时，仓库 source 不能依赖当前目录存在；</li> symlink、ZDOTDIR</code> 和旧版本安装路径都可能造成重复加载或覆盖。</li> </ul> 安装器把这些判断集中处理了：它会根据命令是否存在选择增强功能，根据配置内容选择 bootstrap 或 integrate 模式，根据远程地址决定是否允许更新，并在写入前留下备份。重复运行安装器时，已有 managed block 会被更新，而不是不断追加相同配置。</p> </i></a> 跨平台验证</h2> 这不是只在一台 Mac 上能工作的个人配置。仓库的 GitHub Actions 会在 Ubuntu、macOS 和 Windows/MSYS2 上运行 shell 语法检查、ShellCheck、隔离安装测试和真实依赖安装 smoke test；非 Pull Request 事件还会验证已经发布的一键安装脚本是否能够完成 bootstrap。</p> 因此，项目更关注“安装器能否在不同环境中安全完成初始化”，而不只是 prompt 在作者自己的机器上看起来是否正常。可以在 Actions 页面</a> 查看每次提交的验证结果。</p> </i></a> 安全提示</h2> 远程一键安装本质上会下载并执行仓库中的 shell 脚本。在敏感环境中，建议先 clone 并阅读 install.sh</a>，再决定是否执行。安装器需要系统权限时只调用已有的 sudo</code> 或 doas</code>，不会把密码写入文件。</p> 公开仓库中的所有脚本、配置和提交历史都应视为任何人可读。API token、密码、私钥、公司内部路径和代理凭据应该放在本机的 local 文件或专门的秘密管理工具中，而不是放进仓库。.gitignore</code> 可以降低误提交概率，但不能代替秘密管理，也不能抹掉已经进入 Git 历史的敏感内容。</p> 如果你正在寻找一套“装一次、换机器时少折腾、又不希望接管原有 shell 配置”的 zsh 起点，canxin-zsh</code> 就是为这个场景准备的。</p>

canxin-zsh：把一套不打扰现有配置的 zsh 环境带到每台机器

2026-08-30T00:00:00+00:00

项目地址：canxin121/canxin-zsh</a>
本文介绍项目的定位、安装后的使用体验和设计取舍。具体参数与最新平台支持情况请以仓库的 README</a> 为准。 </blockquote>
很多人第一次整理 zsh 配置时，都会遇到两个相反的问题：要么把一份 .zshrc</code> 直接复制到每台机器上，最后和系统环境、已有插件互相冲突；要么每换一台电脑，就重新手动安装 zsh、Oh My Zsh、主题、插件和各种命令行工具。
canxin-zsh</code> 想解决的是中间这件事：把一套可复用的 zsh 环境、默认工具和安装流程放在同一个仓库里，同时尽量尊重用户已经存在的配置。它可以在 macOS、Linux、WSL、MSYS2 和 Cygwin 中使用，并根据当前平台选择可用的包管理器。
</a> 这个仓库到底是什么</h2> canxin-zsh</code> 不只是几份 dotfiles，也不是一个会接管整台电脑的配置管理器。它由三部分组成： home/.zshrc</code> 和 home/.zprofile</code>：zsh 的入口配置；</li> zsh/rc/common.zsh</code>：alias、工具检测、历史记录、Oh My Zsh 接入和更新函数；</li> install.sh</code> 与 install.ps1</code>：分别负责 POSIX shell 和 Windows PowerShell 场景的安装。</li> </ul> 安装器会把仓库作为一个可更新的 source checkout 保存下来，再让用户的 zsh 配置加载它。这样做的好处是，仓库更新时不需要把一整份新的 .zshrc</code> 覆盖到用户家目录里，也不会因为某一台机器的路径不同而失效。 </a> 安装以后能得到什么</h2> 普通全量安装、且原来的 zsh 配置为空时，得到的是一套可以直接工作的交互式 shell 环境。 </a> 更有信息量的 prompt</h3> 默认会安装并使用 Powerlevel10k</a>。提示符会展示当前目录、Git 分支和工作区状态，也会保留命令执行状态等有助于日常开发的信息。 如果用户已经选择了其他主题，或者家目录中已经有可读的 .p10k.zsh</code>，安装器会优先保留用户自己的选择，不会强行换主题或覆盖 p10k 配置。 </a> Oh My Zsh 与常用插件</h3> 全新配置会使用 Oh My Zsh</a>，并启用一组比较实用的基础插件： git</code>：Git 命令别名和仓库提示；</li> colored-man-pages</code>：让 man 文档更容易阅读；</li> dirhistory</code>：使用快捷键浏览目录历史；</li> extract</code>：用统一命令解压常见压缩文件；</li> sudo</code>：快速为上一条命令补上 sudo。</li> </ul> 此外还会准备以下插件： zsh-completions</code>：补充更多命令的 Tab 补全；</li> fzf-tab</code>：把补全候选项接入交互式选择；</li> zsh-autosuggestions</code>：根据历史命令给出灰色建议；</li> zsh-history-substring-search</code>：按输入内容搜索历史；</li> zsh-syntax-highlighting</code>：对命令输入进行语法高亮。</li> </ul> </a> 历史记录和目录导航</h3> 在全新配置中，历史记录默认保留最多 50,000 条，并启用增量写入、跨 shell 共享和重复命令过滤。输入一部分命令后，按上下方向键可以在历史中搜索包含这段文字的命令。 目录操作也会启用一些适合交互式 shell 的选项：可以直接输入目录名进入目录，使用目录栈快速回到之前的位置，同时避免同一个目录被重复压入目录栈。 Ctrl-E</code> 会调用 zsh 的 edit-command-line</code>，用编辑器打开当前正在输入的命令，适合编辑比较长的命令或多行脚本。 </a> fzf 搜索工作流</h3> 如果系统中安装了 fzf</code>，配置会自动把它接入文件搜索、目录切换和补全预览。fd</code> 或 fdfind</code> 存在时，fzf 会使用它们查找隐藏文件并排除 .git</code>；如果没有，就退回系统自带的 find</code>。 这意味着安装完成后，文件搜索、目录跳转和补全候选项都可以通过交互式筛选完成，而不必每次手写很长的 find</code> 命令。没有安装 fzf 时，普通 Tab 补全和系统命令仍然可以正常使用。 </a> 一组实际可用的 alias</h3> 配置会根据当前机器上实际存在的命令自动选择 alias。下面这些命令是日常最容易用到的一组： l / ls # 有 eza/exa 时增强目录列表，否则保留系统 ls ll # 详细列出文件、隐藏文件和 Git 状态 la # 列出隐藏文件 lt # 以树状形式列出目录 catp FILE # 有 bat/batcat 时高亮并分页查看文件 grep TEXT # 有 ripgrep 时使用 rg 搜索 top # 有 btop 时启动 btop lg # 有 lazygit 时启动 lazygit zreload # 重新加载 zsh 配置 zupdate-all # 更新 Oh My Zsh 和插件/主题 checkout</code></pre> 这些 alias 只会在同名 alias 或 function 尚不存在时定义。如果用户已经有自己的 ls</code>、grep</code> 或 lg</code>，项目不会直接覆盖它们。 </a> 怎么安装</h2> </a> macOS、Linux、WSL 和 MSYS2</h3> 在对应的终端执行： curl -fsSL https://raw.githubusercontent.com/canxin121/canxin-zsh/main/install.sh | bash</code></pre> 安装器会自动检查并尝试补齐 zsh、Git、curl、CA 证书和默认命令行工具。远程命令本身需要当前环境已经有 curl</code> 和 bash</code>；如果需要先审查脚本，也可以 clone 后从本地运行： git clone https://github.com/canxin121/canxin-zsh.git cd canxin-zsh ./install.sh</code></pre></a> Windows PowerShell</h3> 原生 PowerShell 本身没有 zsh。已经安装 WSL、MSYS2 或 Cygwin 后，可以在 PowerShell 中使用项目提供的转发脚本： irm https://raw.githubusercontent.com/canxin121/canxin-zsh/main/install.ps1 | iex</code></pre> 它会优先使用 wsl.exe</code>，其次使用 bash.exe</code>。实际配置安装在哪个环境，取决于最终被调用的 WSL、MSYS2 或 Cygwin。这个命令不会自动安装 WSL，也不能让单独的 Git Bash 变成 zsh。 安装完成后，重新打开终端，或执行： exec zsh</code></pre></a> 依赖会怎么处理</h2> 这个项目不希望用户安装完后才发现一半功能因为缺命令而失效，所以普通安装会默认尝试准备下面这些内容。 </a> 基础运行依赖</h3> zsh</code>：实际运行 shell；</li> git</code>：下载仓库、Oh My Zsh、主题和插件；</li> curl</code>：远程安装与获取内容；</li> CA 证书：确保 HTTPS 下载能够正常验证。</li> </ul> </a> 默认命令行工具集</h3> 默认工具集包括 fzf</code>、ripgrep</code>、fd</code>、eza</code>、bat</code>、btop</code>、lazygit</code> 和 tldr</code>。不同系统的可执行文件名和软件包名可能不同，例如： 作用</th> 可能出现的命令</th> 常见软件包名</th></tr></thead> 模糊搜索</td> fzf</code></td> fzf</code></td></tr> 文本搜索</td> rg</code></td> ripgrep</code></td></tr> 文件查找</td> fd</code> / fdfind</code></td> fd</code> / fd-find</code></td></tr> 目录列表</td> eza</code> / exa</code></td> eza</code></td></tr> 文件查看</td> bat</code> / batcat</code></td> bat</code></td></tr> 系统监控</td> btop</code></td> btop</code></td></tr> Git 终端界面</td> lazygit</code></td> lazygit</code></td></tr> 命令示例</td> tldr</code></td> tealdeer</code></td></tr> </tbody></table> 工具集是普通安装的默认内容，不需要逐项选择。只有想要更轻量的安装时，才使用： ./install.sh --minimal</code></pre> 它会跳过默认工具集，但仍然尝试安装基础依赖。工具集中的单个软件包在某个发行版中不存在时，只会发出警告并继续；基础 shell 仍能工作。zsh</code>、git</code> 或 curl</code> 这类必需命令在安装后仍缺失，则安装会停止。 安装器目前会识别 Homebrew、apt、dnf、yum、pacman、apk 和 zypper。macOS 没有 Homebrew 时不会静默安装 Homebrew；Cygwin 的系统包则需要通过 Cygwin 安装器维护。 </a> 它如何避免破坏已有配置</h2> 这是这个项目最重要的设计取舍：共享配置不能以“把用户的 .zshrc</code> 换成我的版本”为代价。 安装器不会把仓库中的 home/.zshrc</code> 直接复制覆盖用户文件，而是在用户的 ~/.zshrc</code> 和 ~/.zprofile</code> 末尾维护一个可重复更新的区块： # >>> zsh-dotfiles managed block >>> ... # <<< zsh-dotfiles managed block <<<</code></pre> 虽然仓库已经从 zsh-dotfiles</code> 改名为 canxin-zsh</code>，marker 仍然保留旧名称，这是为了让历史安装可以被新版本识别和更新，避免升级后加载两遍配置。 </a> 新配置和已有配置的区别</h3> 空配置会进入 bootstrap 模式，启用完整的默认历史、补全、目录导航、快捷键、Oh My Zsh 和主题；</li> 非空配置会进入兼容集成模式，保留用户已有的主题、插件、历史选项、补全样式和快捷键；</li> 已经加载 Oh My Zsh 时不会重复加载，也不会重设用户的 ZSH_THEME</code> 和 plugins</code>；</li> 检测到 zinit、zplug、zgen、antigen、zimfw、sheldon、prezto、zcomet 等其他框架时，不会再额外启动 Oh My Zsh；</li> 已有 alias、function 和可读的 Powerlevel10k 配置会优先保留；</li> 普通 symlink 会保留，安装器会更新它指向的目标；如果 symlink 直接指向仓库 source 文件，会先安全解除这个自引用关系，避免递归加载。</li> </ul> 如果安装器确实需要修改已有配置，会先在下面的位置创建备份： ~/.config/zsh-dotfiles/backups/</code></pre> 机器特定的设置可以放在： ~/.zprofile.local # PATH、SDK、代理和登录 shell 设置 ~/.zshrc.local # 本机 alias、函数和交互式设置</code></pre> 这些文件不会被仓库覆盖，也不应该提交到公开仓库。对于空配置，它们会自动加载；对于已有非空配置，安装器默认不额外插入加载语句，以免改变原来的加载顺序，可以由用户自行 source。 </a> 安装后如何检查和更新</h2> 本地 clone 的项目可以运行： bin/zsh-doctor</code></pre> 远程安装默认把 source checkout 放在： ${XDG_DATA_HOME:-$HOME/.local/share}/canxin-zsh</code></pre> 因此也可以直接执行： "${XDG_DATA_HOME:-$HOME/.local/share}/canxin-zsh/bin/zsh-doctor"</code></pre> 诊断工具会检查 zsh、Git、默认工具集以及 code</code> 命令是否存在，方便判断某个 alias 或增强功能为什么没有启用。 配置加载后，可以使用： zupdate-all</code></pre> 它会尝试更新 Oh My Zsh 和 $ZSH_CUSTOM</code> 下的 Git 插件/主题 checkout。如果 $ZSH_CUSTOM</code> 里还有用户自己放入的 Git checkout，它们也可能被更新；如果系统有 Homebrew，还会执行 brew update</code> 和 brew upgrade</code>。因此这个命令适合明确希望更新整套开发环境时使用。 安装阶段的更新选项则更细分： ./install.sh --update # 更新远程地址匹配的依赖 checkout ./install.sh --update-source # 更新远程安装管理的 canxin-zsh source checkout ./install.sh --dry-run # 在本地 checkout 中只查看计划，不写配置</code></pre></a> 支持的平台</h2> 项目会根据环境使用对应的系统包管理器： macOS：优先使用已经安装的 Homebrew，也可以使用系统已有的 zsh 和 curl；</li> Debian、Ubuntu、WSL：使用 apt-get</code>；</li> Fedora、RHEL：使用 dnf</code> 或 yum</code>；</li> Arch Linux 和 MSYS2：使用 pacman</code>；</li> Alpine Linux：使用 apk</code>；</li> openSUSE：使用 zypper</code>；</li> Cygwin：先用 Cygwin 安装器准备 git</code>、curl</code> 和 zsh</code>，再运行项目安装器。</li> </ul> 原生 Windows PowerShell 和单独的 Git Bash 都不是 zsh 运行环境。Windows 用户应把 WSL 作为首选，或者使用已经安装 zsh 的 MSYS2/Cygwin。 </a> 这个项目为什么值得单独做一个安装器</h2> 如果只是把几个配置文件放进 Git 仓库，跨平台时很快就会遇到这些问题： macOS、Linux 和 MSYS2 的包管理器完全不同；</li> fd</code>、bat</code> 等工具在 Debian 系统上的命令名可能与 macOS 不同；</li> 有些机器已经有自己的 Oh My Zsh 或其他框架；</li> 用户的 .zshrc</code> 里可能已经有大量 alias、函数和本机变量；</li> 通过 curl | bash</code> 安装时，仓库 source 不能依赖当前目录存在；</li> symlink、ZDOTDIR</code> 和旧版本安装路径都可能造成重复加载或覆盖。</li> </ul> 安装器把这些判断集中处理了：它会根据命令是否存在选择增强功能，根据配置内容选择 bootstrap 或 integrate 模式，根据远程地址决定是否允许更新，并在写入前留下备份。重复运行安装器时，已有 managed block 会被更新，而不是不断追加相同配置。 </a> 跨平台验证</h2> 这不是只在一台 Mac 上能工作的个人配置。仓库的 GitHub Actions 会在 Ubuntu、macOS 和 Windows/MSYS2 上运行 shell 语法检查、ShellCheck、隔离安装测试和真实依赖安装 smoke test；非 Pull Request 事件还会验证已经发布的一键安装脚本是否能够完成 bootstrap。 因此，项目更关注“安装器能否在不同环境中安全完成初始化”，而不只是 prompt 在作者自己的机器上看起来是否正常。可以在 Actions 页面</a> 查看每次提交的验证结果。 </a> 安全提示</h2> 远程一键安装本质上会下载并执行仓库中的 shell 脚本。在敏感环境中，建议先 clone 并阅读 install.sh</a>，再决定是否执行。安装器需要系统权限时只调用已有的 sudo</code> 或 doas</code>，不会把密码写入文件。 公开仓库中的所有脚本、配置和提交历史都应视为任何人可读。API token、密码、私钥、公司内部路径和代理凭据应该放在本机的 local 文件或专门的秘密管理工具中，而不是放进仓库。.gitignore</code> 可以降低误提交概率，但不能代替秘密管理，也不能抹掉已经进入 Git 历史的敏感内容。 如果你正在寻找一套“装一次、换机器时少折腾、又不希望接管原有 shell 配置”的 zsh 起点，canxin-zsh</code> 就是为这个场景准备的。

canxin's blog - Linux

canxin-zsh：把一套不打扰现有配置的 zsh 环境带到每台机器