chrome-devtools-mcp CLI 安装与故障排查实战：全局安装、status 校验与守护进程版本一致性

本文围绕 chrome-devtools-mcp 仓库中 CLI 安装参考文档 展开，讲清 chrome-devtools 命令的一次性全局安装流程、chrome-devtools status 校验命令的底层判定逻辑，以及“命令找不到、权限报错、旧版本残留”三类安装故障的排查手段。读完后你可以独立完成安装、用 status 确认守护进程（daemon）状态与版本一致性，并基于源码证据定位升级失败问题。

1. 为什么是全局安装：chrome-devtools 命令从何而来

安装文档的原始说明非常直接：

Install the package globally to make the chrome-devtools command available. You only need to do this the first time you use it.（全局安装该包即可得到 chrome-devtools 命令，整个使用周期只需执行一次。）

之所以要全局安装，是因为 npm 包 chrome-devtools-mcp 的 bin 字段声明了两个可执行入口（见 package.json 第 6～9 行）：

"bin": {
  "chrome-devtools-mcp": "./build/src/bin/chrome-devtools-mcp.js",
  "chrome-devtools": "./build/src/bin/chrome-devtools.js"
}

执行 npm i -g 时，npm 会在全局 bin 目录下为这两个入口创建符号链接。其中 chrome-devtools-mcp 是 MCP 服务器入口，而本文主角 chrome-devtools 是终端 CLI 入口，其源码位于 src/bin/chrome-devtools.ts。安装完成后，这个文件才会以 chrome-devtools 命令的形式出现在你的 shell 里。

运行前提

仓库对运行环境有明确约束：

• Node.js 版本：package.json 的 engines 字段声明为 ^20.19.0 || ^22.12.0 || >=23（第 101～103 行），即 Node 20.19+ / 22.12+ / 23+；README 的 Requirements 一节同样要求 Node.js LTS、Chrome 当前稳定版（或更新）以及 npm。
• 浏览器：CLI 底层通过 Puppeteer 驱动 Chrome，因此机器上需有可用 Chrome。

2. 安装命令

安装文档给出的标准流程只有两步，且只需执行一次：

npm i chrome-devtools-mcp@latest -g
chrome-devtools status # check if install worked.

几点细节说明：

• -g 表示全局安装，是 chrome-devtools 命令全局可用的前提；
• @latest 确保拉到最新发布版本。README 在 MCP 配置中同样推荐 chrome-devtools-mcp@latest，以始终使用最新版本；
• 第二条 chrome-devtools status 既是文档指定的验证方式，也是后续故障排查的起点——它能告诉你命令是否可用（否则会报 command not found）、后台 daemon 是否在运行、以及运行的版本是否为最新（详见第 3 节）。

3. chrome-devtools status 校验：它到底检查了什么

status 并不只是打印一句话，从 src/bin/chrome-devtools.ts 第 164～197 行的实现看，它的完整逻辑是：

1. 通过 isDaemonRunning(sessionId) 判断 daemon 是否存活。该函数（src/daemon/utils.ts 第 111～123 行）读取运行时目录下的 daemon.pid 文件，取出 PID 后执行 process.kill(pid, 0)——发送 0 号信号只做存活探测、不影响进程；若进程已死则说明是残留的过期 PID 文件。
2. daemon 在运行时，向它发送 status 命令，成功后按如下格式输出：

chrome-devtools-mcp daemon is running.
pid=... socket=... start-date=... version=...
args=...

3. 版本一致性校验：若 daemon 报告的 version 与 CLI 自身的 VERSION（当前仓库为 src/version.ts 中的 1.8.0）不一致，会打印告警：

Warning: Daemon server version (x.y.z) does not match CLI version (1.8.0). Run 'chrome-devtools start' to update and restart the daemon.

4. daemon 未运行时输出 chrome-devtools-mcp daemon is not running.。

3.1 daemon 的通信位置：socket 与 PID 文件

理解 status 的输出有助于理解 CLI 的架构：CLI 本身只是客户端，真正持有浏览器的是后台 chrome-devtools-mcp daemon，二者通过 Unix socket（Linux/macOS）或命名管道（Windows）通信。src/daemon/utils.ts 第 36～59 行的 getSocketPath 给出了具体位置：

• Linux（设置了 XDG_RUNTIME_DIR）：$XDG_RUNTIME_DIR/chrome-devtools-mcp/server.sock；
• Linux/macOS 回退路径：/tmp/chrome-devtools-mcp-<uid>.sock（源码注释说明使用 /tmp 是为了控制在 POSIX socket 路径 104 字符限制以内）；
• Windows：\\.\pipe\chrome-devtools-mcp-<username>\server.sock（路径中附加用户名以避免跨用户命名管道抢占）。

对应的 PID 文件为运行时目录下的 daemon.pid（getPidFilePath，src/daemon/utils.ts 第 85～89 行）。这套机制被端到端测试 tests/e2e/chrome-devtools-start-stop.test.ts 覆盖：每个用例都使用随机 sessionId，先 stop 断言 daemon 未运行，再 start 断言运行，最后 stop 收尾，保证测试互不串扰。

3.2 为什么安装后 daemon 通常显示 "not running"

这是正常现象。从 src/bin/chrome-devtools.ts 第 277～286 行可以看到：CLI 在首次调用任意工具命令时（如 list_pages），会隐式执行 start 拉起 daemon，而 start 又隐含 --viaCli 参数（DEFAULT_CLI_ARGS，第 44 行）。因此 status 在安装后第一次执行时多半报告 daemon 未运行——这恰恰证明命令安装成功、CLI 本身可执行。真正的“工作流”是：

chrome-devtools list_pages            # 首次调用，隐式启动 daemon 与浏览器
chrome-devtools status                 # 此后即可看到 running 状态与版本信息
chrome-devtools navigate_page 1 --url "https://example.com"
chrome-devtools stop                    # 用完显式停止

4. 版本与更新检查机制：@latest 之外的第二道保障

CLI 入口文件顶部（src/bin/chrome-devtools.ts 第 40～42 行）在每次启动时都会调用 checkForUpdates，其提示文案本身就是官方升级路径：

Run `npm install -g chrome-devtools-mcp@latest` and `chrome-devtools start` to update and restart the daemon.

结合 src/utils/check-for-updates.ts 的实现，该机制的行为是：

• 最新版本号缓存在 ~/.cache/chrome-devtools-mcp/latest.json（第 33～38 行）；
• 缓存文件 24 小时内有效则跳过网络检查（第 56～59 行），超期后以分离的后台子进程（detached: true, stdio: 'ignore'，第 85～94 行）去刷新缓存，不阻塞当前命令；
• 当 semver 比较发现本地版本落后于缓存版本时，打印 Update available: <本地> -> <最新> 及升级指引（第 50～54 行）；
• 设置环境变量 CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS 可完全禁用更新检查（第 28 行）。README 的 "Update checks" 一节也记录了该变量。

需要注意一个安装相关的要点：升级 npm 包并不会重启已在运行的 daemon，旧版本 daemon 会继续按旧代码工作，直到你执行 chrome-devtools start（它会先 stop 再拉起新进程，见 start 命令实现第 136～139 行）。这正是安装文档中 "Old version running" 条目背后的深层原因，也是 status 告警提示 “Run 'chrome-devtools start' to update and restart the daemon” 的由来（verifyDaemonVersion，src/daemon/client.ts 第 201～220 行）。

5. 故障排查（Troubleshooting）

以下完整继承安装文档给出的三类问题，并结合源码补充判定依据与处理命令。

5.1 Command not found：chrome-devtools 无法识别

现象：安装命令成功执行，但 shell 提示 command not found。

原因：全局 npm bin 目录不在系统 PATH 中，常见于新装 Node 环境、或切换过 Node 版本管理器后的新终端会话。

处理：

1. 重启终端，或 source 你的 shell 配置文件（.bashrc、.zshrc）使 PATH 生效；
2. 确认全局 bin 目录位置：npm config get prefix 输出的路径下 bin/ 子目录应包含 chrome-devtools 符号链接，并将该目录加入 PATH；
3. 若使用了多套 Node 安装（系统自带 + nvm 等），注意 which chrome-devtools 指向的实际是哪个前缀，避免 PATH 中排在前面的是旧目录。

5.2 Permission errors：安装时出现 EACCES

现象：npm i -g 阶段报 EACCES 或类似权限错误。

原因：npm 全局前缀目录（如 /usr/local/lib/node_modules）当前用户没有写权限。

处理（安装文档的明确建议）：不要使用 sudo，改用以下任一方式：

• 使用 Node 版本管理器（如 nvm），让全局目录位于用户主目录下；
• 或将 npm 全局目录改为用户可写的路径（npm config set prefix <dir>，随后把 <dir>/bin 加入 PATH）。

避免 sudo 的根本原因在于它会让 npm 以 root 写入全局目录，污染文件属主并可能引发后续所有非 root 安装继续失败。

5.3 Old version running：升级后仍在跑旧版本

现象：已经执行了新版安装，但行为仍是旧版；或 chrome-devtools status 输出版本落后、并伴随第 3 节所述的 version mismatch 告警。

处理：安装文档给出的标准命令是——

chrome-devtools stop && npm uninstall -g chrome-devtools-mcp

先停掉 daemon 再卸载，随后重新执行 npm i chrome-devtools-mcp@latest -g 并 chrome-devtools start 拉起新进程。

补充两个基于源码的判断：

• daemon 是长驻进程：CLI 每次命令都是短连接（sendCommand 打开 socket、发一条消息、断开，见 src/daemon/client.ts 第 145～186 行），真正驻留的是 daemon。因此“升级 npm 包”与“重启 daemon”是两件独立的事，漏掉 stop/start 就会命中本问题；
• PATH 指向旧安装：若机器上存在多个全局目录（例如换过 Node 版本管理器），新版本可能装进了 PATH 靠后的目录。用 which chrome-devtools 与 chrome-devtools status 的版本输出交叉确认。

6. 安装验证与后续步骤

一条最小验证链路，确认安装、daemon 生命周期、版本一致性全部正常：

chrome-devtools status                                  # 1. 命令可用
chrome-devtools list_pages                              # 2. 隐式启动 daemon 并返回页面列表
chrome-devtools status                                  # 3. 应显示 running、version 一致
chrome-devtools stop                                    # 4. 收尾

若怀疑是 daemon 侧问题而非安装问题，可参考 docs/cli.md 的 Troubleshooting：先 chrome-devtools stop 再重试，并用 DEBUG=* 环境变量打开详细日志（如 DEBUG=* chrome-devtools list_pages）。更完整的命令行用法（start/stop/status 之外的工具命令、--output-format=json、--workspace 文件访问限制等）见 docs/cli.md 与 skills/chrome-devtools-cli/SKILL.md；start 转发参数（--headless、--userDataDir、--workspace 等）的完整清单可通过 chrome-devtools start --help 查看——从 src/bin/chrome-devtools.ts 第 125～162 行可见，start 支持将后续参数原样转发给底层 MCP 服务器，但 CLI 场景下会对参数集做过滤（getCliOptions，第 52～65 行，例如移除了 CLI 无法序列化的 viewport 选项）。

最后提示：仓库还内置了 --sessionId 隐藏选项（src/bin/chrome-devtools.ts 第 75～84 行），可用不同 session ID 隔离出多个互相独立的 daemon 实例（socket 与 PID 文件路径均按 sessionId 区分，见 src/daemon/utils.ts 第 36～59 行）。在 CI 或并行自动化场景中，这能让多个流程共享同一台机器而不互相踩踏；它不属于安装流程，但对理解“为什么 status 显示某个 daemon 在跑”很有帮助。