WakaTime状态栏显示“Idle”根本原因是wakatime-cli未安装或不可访问、~/.wakatime.cfg文件缺失/权限错误/内容不全，或VS Code未完全重启；三者任一出错即导致静默失效。
装上插件不等于开始追踪——wakatime-cli没就位、~/.wakatime.cfg文件权限错或内容缺项、VS Code 没完全重启，三者任一出问题，状态栏就卡在 WakaTime: Idle 或报 Not authenticated。
为什么装完插件后状态栏一直显示 “Idle”？
根本不是插件没启用，而是它依赖的本地命令行工具 wakatime-cli 没装好，或配置文件未被正确读取。
-
wakatime-cli是实际干活的组件，VS Code 插件只负责转发事件；终端运行wakatime-cli --version报command not found就说明它根本不在PATH里 - macOS/Linux 用户常见于自动安装脚本被代理中断，
curl下载静默失败；Windows 用户用 PowerShell 脚本常因权限问题把二进制文件写到错误路径 - 手动补救：去 GitHub releases 页面 下载对应系统架构的
wakatime-cli，解压后放到~/.wakatime/（macOS/Linux）或C:\wakatime\（Windows），再把该路径加进系统PATH - 装完必须关掉所有 VS Code 窗口再重开——插件只在启动时扫描一次
wakatime-cli
API 密钥填在哪才真正生效？
VS Code 设置里写的 wakatime.apiKey 只起“首次引导”作用，后续所有认证都靠本地 ~/.wakatime.cfg（Windows 是 %USERPROFILE%\wakatime.cfg）。
- 该文件必须存在，且至少包含两行：
[settings]和api_key = xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx - macOS/Linux 下必须执行
chmod 600 ~/.wakatime.cfg，否则 CLI 会拒绝读取（日志里出现Permissions too open） - Windows 用户别用记事本保存——它默认加 BOM，导致解析失败；用 VS Code 或 Notepad++ 保存为
UTF-8 no BOM - 改完配置不能点“重载窗口”，得彻底退出 VS Code 再启动
项目名总显示 “Unknown Project” 怎么办？
WakaTime 不看 VS Code 工作区名、不读 .code-workspace 文件，它只认离当前文件最近的 .git 目录名。没 Git 或 Git 在上级目录，就 fallback 到 Unknown。
- 最稳解法：在每个你想单独统计的项目根目录下新建
.wakatime-project文件，里面只写一行纯文本项目名，比如payment-service（不要引号、空格或注释） - monorepo 场景下，若子包没独立
.git，又不想全堆成一个项目，就别依赖 Git 推导——老老实实放.wakatime-project - 临时文件、无后缀文件、路径匹配
ignore规则（如含node_modules）的编辑行为，语言和项目都不会被识别
如何验证是否真正在追踪？
别只盯着状态栏图标，直接查日志和输出面板更可靠。
- 打开 VS Code 输出面板（
Ctrl+Shift+U），切换到WakaTime频道，正常会有类似Heartbeat sent for /path/to/file.py的日志 - 查看
~/.wakatime.log（Windows 是%USERPROFILE%\wakatime.log），重点搜ERROR、TimeoutError、Connection refused - 如果日志里反复出现
No such file or directory: ~/.wakatime.cfg，说明文件路径或权限仍有问题 - 真实编码行为（输入、保存、切换标签页）才会触发上报；开着编辑器但不动键盘，不会产生任何心跳
最难调的从来不是第一步安装，而是 ~/.wakatime.cfg 权限、wakatime-cli 路径、以及那个必须「完全退出再重开」的重启动作——这三处任意一个漏掉，整个链路就静默失效，连错误提示都不给你。
