WakaTime插件在VS Code中“装上了≠在工作”，根本原因是依赖本地~/.wakatime.cfg文件（Windows为%USERPROFILE%\wakatime.cfg），该文件必须存在、权限正确（macOS/Linux需chmod 600）、格式规范（含[settings]和api_key），且项目根目录需配置.wakatime-project文件以准确识别项目名；修改后须完全重启VS Code。
WakaTime 插件在 VS Code 中“装上了≠在工作”，很多用户反馈状态栏显示 WakaTime: Idle、日志里反复报 WakaTime: Not authenticated，或者项目名全是 Unknown Project——根本原因是插件启动后并不依赖 VS Code 设置里的 API key 字段，而是必须读取本地 ~/.wakatime.cfg 文件，且该文件权限、路径、内容任一出错都会导致整个追踪链路静默失败。
~/.wakatime.cfg 文件必须手动创建且权限严格
- VS Code 设置中填的 API key 仅用于首次引导，后续所有认证和配置都以
~/.wakatime.cfg（Windows 是%USERPROFILE%\wakatime.cfg）为准 - 如果该文件不存在，或内容为空/格式错误，插件会退回到未认证状态，状态栏卡在
Idle，日志里出现No such file or directory: ~/.wakatime.cfg - 必须包含至少两行：
[settings] api_key = xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
- macOS/Linux 下需立即执行：
chmod 600 ~/.wakatime.cfg；Windows 用户需确认文件未被记事本另存为 UTF-8 with BOM（推荐用 VS Code 或 Notepad++ 保存为 UTF-8 no BOM） - 修改后必须完全重启 VS Code（不是重载窗口），因为插件只在启动时读一次该文件
项目名显示为 Unknown Project 的真实原因和解法
-
WakaTime默认靠「离当前文件最近的.git目录名」识别项目，不是靠 VS Code 工作区名、文件夹名或.code-workspace文件 - 常见失效场景：
- 打开的是子目录（如
/monorepo/packages/frontend），但.git在/monorepo，它就取monorepo而非frontend - 单个文件打开（无任何 Git 上下文）
- 使用 pnpm workspace 或 turborepo，但子包没独立 Git
- 打开的是子目录（如
- 稳定解法：在每个实际想区分的项目根目录下放一个
.wakatime-project文件，内容就是你希望显示的项目名，例如：backend-api-v2
- 不要依赖
wakatime-cli --project命令行参数覆盖——VS Code 插件不传这个参数，只认文件系统级配置
wakatime-cli 卡住或上报失败的三个关键检查点
- 插件本身不统计也不上传，它只是调用本地
wakatime-cli（Python 工具），所有失败本质是 CLI 层问题 - 检查方式：打开 VS Code 输出面板（
Ctrl+Shift+U），切换到WakaTime日志，搜ERROR或TimeoutError - 常见根因：
- 公司网络走 HTTP 代理但未配置 CLI：需在
~/.wakatime.cfg中加proxy = <a href="https://www.php.cn/link/2cd012557855b6a1e29ef1fdddbbabcf">https://www.php.cn/link/2cd012557855b6a1e29ef1fdddbbabcf</a> - SSL 验证失败（尤其老旧 Linux 发行版）：加
ssl_verify = false（仅内网可信环境） -
wakatime-cli未安装或版本过旧：终端运行wakatime-cli --version，若报 command not found，说明插件自带的 CLI 未正确部署，可手动安装：pip install wakatime，再确认路径是否被加入$PATH
- 公司网络走 HTTP 代理但未配置 CLI：需在
真正让 WakaTime 开始可靠打点的，从来不是“点安装”那一下，而是 ~/.wakatime.cfg 是否存在、是否可读、是否写对了 key，以及项目目录里有没有那个不起眼但决定统计精度的 .wakatime-project 文件。其他所有功能——状态栏显示、团队数据、AI 分析——都建立在这两层文件配置稳固的前提下。
