1. 账单对不上的那天，我想起来要装 ccusage
上周我收到一份月度账单，发现用量比预想中多出一截。当时我脑子里第一个反应就是：到底哪个项目的哪一次会话在烧 token？结果在 Claude Code 官方界面上翻了半天，只能看到总的趋势和几个粗粒度的卡片，连按项目拆分的连续报表都拿不出来。也是在那个下午，我装上了这个系列文章的主角——ccusage，一个专门用来统计 Claude Code 使用情况的命令行工具。
如果你平时也用 Claude Code 写代码、跑批处理任务，或者像我一样在多个仓库之间来回切换，迟早会到需要"按维度拆解用量"的这一步。ccusage 的价值不在于多高级，而在于它把散落在本地日志里的 token 消耗、会话记录和成本估算重新聚合起来，变成一个能随手查的数。这个系列第一篇文章聊的是 Claude Code 的基础工作流，这篇就接着往下讲安装。整篇内容只围绕一件事：把 ccusage 装起来、跑通、用明白，并把我装完之后踩过的坑一一交代清楚。
1.1 一个反直觉的事实：Claude Code 比你想象中更"话痨"
Claude Code 的工作方式决定了它每完成一个小任务，就可能产生几十次模型请求。你在终端里看到的每一条工具调用结果，背后几乎都对应一次包含输入和输出 token 的往返。这些往返都会落在本地日志里，形成一条条 JSON 记录。
你随便打开一个项目目录下的日志文件，肉眼会看到类似这样的结构（字段在不同版本里略有变动，但大致是相通的）：
{ "timestamp": "2026-05-20T14:32:11.000Z", "projectName": "simulated-project-x", "conversationId": "conv_xxxxx", "model": "sonnet-4-5", "usage": { "input_tokens": 4521, "output_tokens": 1834, "cache_read_tokens": 2100, "cache_write_tokens": 0 } }看到这个结构你就明白了：统计工具不需要额外埋点，也不需要有网才能跑，它只是在本地把这些散落的记录汇总成报表。这也是我最终选择 ccusage 这类工具而不是自己写脚本去调平台 API 的原因——本地日志最全、最忠实，也最容易做历史回溯。你完全可以理解成：Claude Code 每天都在你硬盘上写日记，而 ccusage 就是那个帮你把日记按周、按项目、按模型整理成表格的助理。
1.2 哪些场景下 ccusage 属于"刚需"
- 多项目并行时，想知道每个项目的 token 消耗，以便判断这个项目是否值得继续推进。
- 给团队或工作室做预算拆分时，需要按会话或者按项目给出一个能对得上号的成本数据。
- 想对比不同模型路线的成本差异，比如把同一批任务分别跑在不同模型上，量化哪条路线更划算。
- 在 CI 流程里想加一道"若当日消耗超阈值则告警"的检查，本地统计工具天然适合做这件事。
以上这些情况一旦出现，你需要的就不再是一张官方趋势图，而是一个能输入命令、输出结构化结果的小工具。ccusage 的定位就是这个。它不是一个花哨的看板，而是一把能随时从口袋里掏出来的尺子。
2. 装之前先确认三件事：Node 版本、日志开关与目录权限
安装本身只有几条命令，但如果你跳过前置检查，后面很容易卡在一个莫名其妙的报错上。这一节我把装之前必须确认的几件事展开细讲，这些检查花不了两分钟，却能让整个安装过程顺滑很多。
2.1 Node.js 环境：版本和包管理器都要对
ccusage 作为一个基于 Node 的 CLI 工具，对环境的第一要求就是可用的 Node 运行时。通常需要 Node 16 及以上，建议直接用到 18 或 20 的 LTS 版本。打开终端输入：
node -v npm -v两个命令都能正常返回版本号，才说明基础环境没问题。如果你是通过某种版本管理工具安装的 Node，那要留意当前终端激活的到底是哪个版本——我见过有人在系统目录和用户目录下各装了一套 Node，导致全局安装位置不对，命令怎么都找不到。
如果 npm 提示没有权限，最常见的原因是全局安装目录需要管理员权限。两种做法任选其一：一是用 sudo 安装（简单，但后续每次升级都容易遇到权限问题）；二是把 npm 全局安装目录改到用户目录下，这个方案我比较推荐，具体配置写在 3.1 里专门讲。不要觉得这一步啰嗦，全局目录的规划直接影响日后升级工具的心态。
2.2 日志开关：确认 Claude Code 是否在写本地记录
ccusage 的数据源是 Claude Code 的本地日志。默认情况下，Claude Code 会为每个项目目录在 ~/.claude/projects/ 下生成对应名称的日志文件（通常是 .jsonl 格式），但有些自定义配置可能关闭或改写了日志行为，所以装之前别急着装工具，先把数据源确认好。
方法很简单：打开 Claude Code，在一个项目目录里随便问一句"你好，请回复 ok"，然后退出，去看日志目录：
ls -lt ~/.claude/projects/正常情况会看到按项目目录名命名的文件夹，里面是带时间戳的日志文件，最近修改时间应该是刚才那一下。如果你看到的是空白目录，就要去检查 Claude Code 的配置文件里有没有把日志路径改掉，或者是否因为某些安全策略阻止了写入。这个检查是后续一切统计的前提：工具读不到日志，装得再漂亮都是空转。
2.3 目录与跨平台权限：容易被忽略的坑
在 macOS 和 Linux 上，~/.claude 目录通常没有问题。但在 Windows 上，路径习惯不一样，而且 PowerShell 的环境变量处理方式也不同。如果你在 Windows 上使用，建议在用户级别设置一个指向 Claude Code 配置目录的环境变量，再检查当前用户对那个目录是否有写入权限。
另一种常见情况：通过公司配发的电脑使用，系统策略可能把用户主目录做成比较严格的权限模型。所以看到 "EACCES: permission denied" 这类字样时，第一反应不是去重装 ccusage，而是先确认日志目录本身能不能读写。说到底，ccusage 只是个读者，如果它读不到文件，问题基本都出在前面这几层。
我把安装前的检查项整理成一张小表，方便你照着做：
| 检查项 | 检查命令 | 达标标准 |
|---|---|---|
| Node 版本 | node -v | 返回 v18 或更高（至少 v16） |
| npm 可用 | npm -v | 返回版本号 |
| 日志存在 | ls -lt ~/.claude/projects/ | 能看到项目目录和日志文件 |
| 日志可读 | 用文本工具打开某条日志 | 能正常输出含 usage 字段的 JSON |
| 目录可写 | 新建临时文件再删除 | 无权限报错 |
3. 三选一安装方式：全局 npm、Homebrew、直接拉二进制
前置检查做完，就可以正式安装了。我实际试过三条路线，各有适用场景。这一节不只是给命令，会把每条路线的选择逻辑也解释清楚，方便你结合自己的习惯做决定。
3.1 路线一：npm 全局安装（推荐优先试这条）
npm 全局安装是三条路线里最贴合工具特性的，因为 ccusage 本质上就是 Node 生态里的一个命令行包，用 npm 管理它的安装和升级最顺理成章：
npm install -g ccusage安装后先跑一下版本确认：
ccusage --version如果你之前遇到过全局安装权限问题，建议先把全局目录指到用户目录，避免每次都要提权：
npm config set prefix ~/.npm-global然后把 ~/.npm-global/bin 加进 PATH（macOS 和 Linux 写进 ~/.zshrc 或 ~/.bashrc，Windows 在系统环境变量里追加路径），重新打开终端即可。这样做的直接好处是以后执行 npm update -g ccusage 时不会再碰到权限拦截，适合把它当成常备工具长期使用。这条路线也最适合那些"什么都想用最新版"的人——npm 上通常第一时间就能拿到新版本。
3.2 路线二：Homebrew 安装（适合已经用 brew 统一管理工具的人）
如果你平时习惯"任何命令行工具都想用 brew 装"，那这条路线更符合直觉：
brew install ccusageHomebrew 的优点是会自动处理依赖、自带版本管理，卸载也干净。但它的更新节奏通常比 npm 慢半拍。想想看，macOS 用户如果已经习惯了用 brew bundle 统一管理开发环境，多一个 ccusage 并不会增加额外的认知负担。而如果你更想要第一时间拿到新功能、新适配，npm 路线会更直接。
另外补充一句：Linux 上也有对应的包管理器选项，不过不同发行版的命令差异较大，不如 npm 这条路线通用。如果你在服务器上装，我会更推荐 npm 或二进制方式，因为服务器环境本身未必有图形化包管理器的习惯。
3.3 路线三：直接拉二进制或源码运行（适合特定版本和二次开发）
如果你想锁定某个具体版本跑在生产环境，或者打算研究源码改一下统计口径，那就绕开包管理器，直接从项目的发布页面下载对应平台的二进制压缩包，解压后把可执行文件放到 PATH 目录下。
还有一种更灵活的方式是直接从仓库拉源码运行：
git clone https://example.invalid/ccusage-repo cd ccusage-repo npm install npm run build node dist/cli.js --help这种方式不经过包管理器，最适合在 CI 或容器镜像里固定某个 commit 来使用。缺点是没有全局命令别名，需要自己软链一下，升级也得手动拉代码。它不算常规首选，但作为一个后备方案心里有数就好。
三条路线的对比我总结一下：
| 方式 | 适用人群 | 优点 | 缺点 |
|---|---|---|---|
| npm 全局 | 多数开发者 | 更新快、与 Node 生态一致 | 需要管理 PATH 与全局目录 |
| Homebrew | macOS 重度 brew 用户 | 依赖管理统一、卸载干净 | 更新可能滞后 |
| 二进制/源码 | CI、需要固定版本或二次开发 | 可锁定版本、便于改造 | 升级靠手动，无全局命令 |
4. 第一次运行：确认数据路径、看输出字段、理解统计口径
安装完成只是第一步，真正影响体验的是第一次运行时的平滑程度。这一节从"ccusage 怎么知道去哪读日志"开始，把首次运行的完整链路走一遍。
4.1 工具如何定位日志目录
ccusage 在运行时需要知道 Claude Code 的配置目录。多数情况下它会按默认路径去探测，也就是 ~/.claude。如果探测失败，就需要手动通过环境变量或参数指定。具体环境变量名在不同版本里不完全一致，我建议先执行：
ccusage --help看输出里的参数说明部分，找到和日志目录、配置相关的选项。这一步非常重要，因为 Claude Code 本身也在频繁更新，日志目录的默认值也可能随版本变化，以你当前安装版本的帮助信息为准，而不是以任何一篇教程（包括这篇）为准。
如果日志目录被手动改过，比如为了统一管理放到工作区里，那就在运行命令时显式指过去：
ccusage --log-dir /path/to/claude-logs4.2 理解输出字段：不只是看一个总数
首次跑出结果后，你会看到类似这样的汇总：
项目 会话数 输入token 输出token 估算成本 simulated-a 23 1,204,552 186,430 $7.42 simulated-b 12 486,210 98,210 $2.11字段含义并不复杂，但有两处容易误解。第一处是 token 数字：它通常包含缓存命中的 token，而不是只算实际新消耗的部分。不同版本对这个字段的归类方式有差异，如果你发现 ccusage 统计的总成本比官方账单偏高，先看看是不是缓存口径导致的。第二处是成本估算：它基于内置的按模型单价换算表计算，只适合作为参考，不适合当成最终账单。不同模型、不同计费阶段的价格表会有变化，ccusage 的作者通常会在新版本里同步更新，所以升级工具本身也是在升级价格表。
4.3 首次运行常见的三个"预期管理"问题
- 第一次扫描可能很慢：如果日志文件积累了几百 MB，需要一点时间解析。不要立刻以为卡死了，看 CPU 占用就知道它在干活。
- 输出可能为空：多半是日志目录路径不对，或者 Claude Code 版本太新、日志字段结构变化导致工具还来不及适配。先确认日志文件确实存在且能手动搜到 usage 字样。
- 不同项目目录同名时会被合并：如果两个仓库的文件夹都叫 frontend，日志目录会按项目名归类，统计时可能被识别成同一个项目。解决办法是在 Claude Code 中给项目设置不同的名称标识，或者按日志目录拆分处理。
5. 安装后最容易踩的五个坑，以及排查顺序
如果说前面是顺利路径，这一节就是我在实际安装和使用中反复遇到的异常情况。我把它整理成一份排查清单，按出现频次排序，你照着顺序走就能少走弯路。
5.1 报错集中在 EACCES 和 ENOENT
安装阶段最容易撞上的两类报错：EACCES 表示文件权限不足，ENOENT 表示文件或目录不存在。前者去检查 npm 全局目录权限或日志目录的可写性；后者去检查路径拼写，以及 Claude Code 是否真的在预期位置生成过日志。
一个小技巧：在怀疑路径问题时，不要直接改 ccusage 的配置，而是先用 find 命令把日志文件的实际位置找出来：
find ~ -name "*.jsonl" 2>/dev/null | grep -i claude | head -20看到实际路径后，再对照工具输出里的路径信息，就能判断到底是路径问题还是权限问题。别小看这个命令，它比瞎猜高多了。
5.2 Claude Code 升级后突然解析失败
这类坑最有代表性。Claude Code 的日志结构没有经过正式版本化约定，模型字段、token 计数字段的组织结构可能在小版本升级里就发生变化。前一晚还用得好好的工具，第二天某次 Claude Code 自动更新后突然输出解析错误，或者解析行数为 0。
这时候的正确步骤是：
- 先打开一条最新的日志记录，肉眼确认结构。
- 对比 ccusage 的版本发布说明，确认是否已适配新的日志结构。
- 如果工具还停留在旧版本，先升级 ccusage。
- 如果升级后依然有问题，把最小复现样本（去掉内容、只保留字段结构）提交给仓库维护者。
整个过程里最重要的一点：别把原始日志直接删了重来。日志文件是你唯一的历史数据，就算工具暂时读不了，也不要急着清理空间。我曾见过有人为了排除问题把历史日志全删了，结果工具修好了，数据也没了，后悔都来不及。
5.3 统计成本与官方账单对不上
这个坑九成集中在缓存和模型版本的口径差异上。官方账单可能按实际计费序列累加，而本地日志里的 usage 字段可能包含估算值或缓存相关项。ccusage 里通常会提供口径参数，例如是否统计缓存 token、是否使用自定义单价表。
我的建议是：先跑一次"只看输入和输出 token 总数"的统计，然后和 Claude Code 内置页面的总数对比。如果总数一致，说明日志解析没问题，差异只来自单价表；如果总数对不上，再考虑缓存字段的归类问题。这样一步步缩小范围，就能定位到具体原因。
5.4 Windows 下的路径分隔符与换行问题
在 Windows 上，路径分隔符是反斜杠，而 JSON 里的反斜杠是转义符。如果日志目录的绝对路径包含反斜杠，命令行传参时容易出歧义。稳妥做法是把路径写进环境变量，然后在引号内传入，尽量避免手写带反斜杠的长路径。
另一个细节是换行符。如果你用代码编辑器或某些脚本处理过日志文件，Windows 的 CRLF 换行可能干扰解析。遇到混乱时，先确认日志文件的换行符类型，必要时用文本工具统一成 LF。
5.5 多账号或密钥轮换导致统计串项目
一个容易被忽略的场景：同一台机器上如果用过多个账号或密钥，Claude Code 的日志里可能混有不同账号的会话记录。如果你只针对某个账号做统计，就会看到不符合预期的数据。
处理方式也很简单：不要在同一环境中混合使用不同账号，或者根据日志字段里的账号标识做过滤。ccusage 如果支持按账号过滤参数，就用参数过滤；不支持就先把日志按账号拆分，再分别统计。
6. 把 ccusage 从"工具"变成"预算仪表盘"：我现在的用法
工具装完之后，剩下的是怎么把它用得顺手。这一节分享几个我实际在用的工作流，也是从"会装"到"会用"的关键过渡。
6.1 每日收尾：一条命令复盘当天的消耗
我现在有一个固定习惯：每天下班前跑一次当日统计，只关心两个数字——今天的总 token 消耗和最大的三个项目。这不需要打开任何面板，一条命令就完事：
ccusage --since today --sort cost --limit 5如果发现某天的消耗异常放大，我会顺手用时间范围把那次会话揪出来。这个动作在月初和月底尤其有用，因为能提前预判账单趋势，而不是等账单发出来才惊讶。说白了，它把"用量焦虑"转化成"用量掌握"。
6.2 每周报告：把 markdown 输出喂给文档仓库
ccusage 支持把统计结果导出为 markdown 或 JSON，我每周一早上会生成一份上周报告，追加到项目文档里。格式不重要，重要的是它让"这个月 token 预算消耗到哪了"成为一个可以持续追踪的指标。哪怕团队里只有我一个人在看，这个记录也会成为后续判断"要不要换更经济的模型路线"的关键证据。
6.3 模型路由的判断依据
如果你曾经在几个模型之间犹豫，ccusage 能帮你把"感觉上哪个更划算"变成真实数据对比。我做过一次实测：同一批需求分别用不同模型跑一个周末，最后用 ccusage 导出成本对比。结论和我预想的不完全一样——有些模型单次报价低，但输出长度长，综合成本反而更高。没有这种本地统计，我很难单独注意到这个差异。
6.4 更进一步的自动化：集成到 CI 或定时任务
我的使用还停留在个人工具层面，但它完全可以往前再走一步：在每天定时任务里跑一次扫描，把超阈值的结果推送到消息通道；或者把 ccusage 放进 CI 流程，在每次构建前检查是否超过配额，提前止损。这些做法的共同前提是——工具必须已经稳定跑通，且你完全理解它的输出口径。所以别急着上自动化，先把第 4、5 两节的细节吃透，再考虑扩展。
就我个人的体会而言，ccusage 最难得的不是它的统计能力，而是它逼着你想清楚一个问题：你的 token 消耗到底花在了哪里。这个问题想明白了，安装过程中那些坑也就都变成值得踩的了。下次系列更新，我打算聊聊如何基于 ccusage 的数据做成本优化和模型路线调整，到时候再把这次的报表数据拿出来对一对。
