Windows用户如何安装ccstatusline-zh:PowerShell、Bun与固定版本实战指南
Windows用户如何安装ccstatusline-zh:PowerShell、Bun与固定版本实战指南
ccstatusline-zh 是 Claude Code CLI 的中文汉化版可定制状态栏格式化工具(当前中文包版本 2.2.33),支持在 Windows 的 PowerShell 5.1+/7+、命令提示符和 WSL 中运行。本文带你用 3 步完成 Windows 安装:装好 Bun 或 Node.js → 启动中文 TUI 配置界面 → 选择「固定全局安装」锁定版本,顺便解决执行策略报错、状态栏换行、Powerline 乱码等 Windows 高频问题。
一、安装前准备:Windows 环境要求
在动手之前,确认你的环境满足以下条件:
| 条件 | 说明 |
|---|---|
| 包管理器 | Bun(推荐)或 Node.js(≥ 14.0.0,见 package.json) |
| 终端 | PowerShell 5.1+ / PowerShell 7+ / Windows Terminal |
| Git | 状态栏大量组件依赖 Git,建议 winget install Git.Git |
| 字体 | 使用 Powerline 主题时需 Nerd Font(见第五节) |
💡 为什么推荐 Bun?上游在 Windows 上的实测显示,
bunx ...@latest每次重绘都要重新解析版本标签,固定版本安装后延迟明显更低;而 Bun 启动本身也比 Node 更快。
二、两种方式安装:Bun 路线与 npm 路线
路线 A:Bun(推荐)
打开 PowerShell,依次执行:
# 1. 安装 Bun
irm bun.sh/install.ps1 | iex
# 2. 启动 ccstatusline 配置 TUI
bunx -y ccstatusline@latest
路线 B:Node.js / npm
如果已安装 Node.js,直接用 npx:
npx -y ccstatusline@latest
两条命令都会打开交互式 TUI 配置界面。此时你已经在 TUI 内,不要急着退出——下一节要在这里完成最关键的一步。
详细安装说明见 docs/WINDOWS.md。
三、固定全局安装:一次锁定,告别版本漂移
这是 Windows 用户最容易忽略、但收益最大的一步。
在 TUI 主菜单进入「安装到 Claude Code」,你会看到两个选项(界面文案来自 src/tui/components/InstallMenu.tsx):
- 自动更新:通过
npx/bunx运行@latest,每次启动有少量包解析开销 - 固定全局安装:把当前 ccstatusline 版本全局安装下来,把命令写为
ccstatusline,以后直接运行即可
推荐选「固定全局安装」,它还会帮你把 command 字段写进 Claude Code 配置:
{
"statusLine": {
"type": "command",
"command": "ccstatusline",
"padding": 0,
"refreshInterval": 10
}
}
配置位置在 %USERPROFILE%\.claude\settings.json(可通过 CLAUDE_CONFIG_DIR 环境变量改为自定义目录)。
⏱
refreshInterval仅在 Claude Code ≥ 2.1.97 时生效,取值 1–60 秒,也可在 TUI 中后续调整。
安装完成后,随时运行 ccstatusline 即可重新打开 TUI 调整状态栏;「管理安装」菜单还能检查 npm 更新、执行全局更新或卸载。
四、Windows 专属设置:宽度、字体与 CI
1. 状态栏换行?手动指定终端宽度
Windows 原生宽度探测在非 WSL 环境下不可用,状态栏可能异常换行。启动 Claude Code 前设置:
$env:CCSTATUSLINE_WIDTH="160"
claude
该变量必须在启动 Claude Code 的同一个终端中设置,才能让状态栏命令继承到。
2. Powerline 符号显示为方块?安装 Nerd Font
推荐直接用 Windows Terminal(原生支持 Powerline 字体并自动识别),再通过 winget 安装字体:
winget install DEVCOM.JetBrainsMonoNerdFont
然后在终端设置的 settings.json 中把字体设为 JetBrainsMono Nerd Font 即可。
3. 想用 Git CI 状态组件?
安装 GitHub CLI 并登录(仅限 GitHub 仓库,读取当前分支 PR 的 CI 检查):
winget install --id GitHub.cli --source winget
gh auth login
分支没有 PR、PR 没有检查、或 token 无权限时,组件会显示 -。
五、常见报错与排查清单
| 问题 | 快速解法 |
|---|---|
| PowerShell 报 "Execution Policy" 错误 | Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser |
| Git 命令无法识别 | 先 git --version 检查;未安装则 winget install Git.Git |
| 安装时权限报错 | 用非全局安装 npx -y ccstatusline@latest,或以管理员身份运行 PowerShell |
| Windows Defender 拦截执行 | 在 Windows 安全中心「病毒和威胁防护」中为 ccstatusline 二进制位置添加排除项 |
| Powerline 显示问号/方块 | 安装 Nerd Font 并在终端设置中指定字体 |
辅助可执行文件(Git、JJ、gh、SSH 等)只会从 PATH 中的绝对路径目录解析,空条目和相对路径会被跳过——把工具装进 PATH 列出的绝对目录里就不会出问题。
六、进阶:WSL 用户可直接按 Linux 流程走
如果你在 WSL 中运行 Claude Code,ccstatusline 体验更好:
curl -fsSL https://bun.sh/install | bash
source ~/.bashrc
bunx -y ccstatusline@latest
WSL 下享受原生 Unix 路径处理和更佳的字体渲染,与 Linux 工作流无缝衔接。
写在最后
回到核心流程,Windows 安装其实就三句话:
- 装运行时:Bun(
irm bun.sh/install.ps1 | iex)或 Node.js - 进 TUI:
bunx -y ccstatusline@latest或npx -y ccstatusline@latest - 锁版本:在 TUI 中选「固定全局安装」,之后直接运行
ccstatusline即可
完成后,你的 Claude Code 底部就会出现一条全中文、可自由编排 90+ 组件的状态栏。更多组件列表与 TUI 快捷键,参见 README.md 与 docs/USAGE.md;Windows 完整文档见 docs/WINDOWS.md。
