【深度解析】从 claude 命令到 cli.js 的完整执行链路

【解析】从 `claude` 命令到 `cli.js` 的完整执行链路

本文以 Windows 环境下的 Claude Code 为例，完整还原一条命令从输入到执行的全过程，涵盖 Node.js 运行时、npm 全局安装机制、PATH 环境变量等核心概念。

一、整体架构：三层结构

在理解细节之前，先建立一个全局视角。执行 claude 命令，本质上经过三层：
你输入 claude
Shell 通过 PATH 找到 claude.ps1 / claude.cmd
脚本调用 node.exe 执行 cli.js
Node.js 运行时加载 JavaScript 代码
操作系统：CPU / 内存 / 文件系统

Node.js 是 JavaScript 的运行时环境，负责将 .js 文件翻译成机器码并执行。
Claude Code 本质上是一堆 .js 文件 + package.json，没有 Node.js 就只是普通文本。
claude** 命令**只是一个"跳板脚本"，真正干活的是 node.exe。

二、npm 全局安装后的文件结构

执行 npm install -g @anthropic-ai/claude-code 后，npm 会在全局 prefix 目录生成文件。

全局目录在哪里？

plain 复制代码

npm config get prefix   # 查看全局前缀目录
npm root -g             # 查看 node_modules 位置

Windows 默认路径为 C:\Users\<用户名>\AppData\Roaming\npm\，也可以自定义（如本文示例的 D:\software\nodejs\prefix\）：

plain 复制代码

npm config set prefix "D:\software\nodejs\prefix"

实际目录结构

plain 复制代码

D:\software\nodejs\prefix\
├── node_modules\
│   ├── @anthropic-ai\
│   │   └── claude-code\
│   │       ├── cli.js        ← 真正的程序入口
│   │       └── package.json
│   ├── openclaw\
│   ├── opencode-ai\
│   └── mcporter\
│
├── claude          ← 无扩展名，给 Git Bash / WSL 用
├── claude.cmd      ← 给 cmd.exe 用
└── claude.ps1      ← 给 PowerShell 用

为什么每个命令有三个入口文件？

npm 在 Windows 上为每个全局命令自动生成三种格式，适配不同终端：
npm install -g
claude

（无扩展名）
claude.cmd
claude.ps1
Git Bash / WSL

Unix 风格终端
cmd.exe
PowerShell

三、入口脚本内容解析

三个文件核心逻辑完全一样，只是语法不同：

claude.ps1（PowerShell）

powershell 复制代码

& node "$PSScriptRoot\node_modules\@anthropic-ai\claude-code\cli.js" $args

claude.cmd（cmd.exe）

plain 复制代码

@node "%~dp0\node_modules\@anthropic-ai\claude-code\cli.js" %*

关键点：%* / $args 会把你输入的所有参数原样透传给 cli.js。

四、PATH 环境变量工作机制

PATH 是一个有序的目录列表，告诉 shell "查找命令时，去这些地方找"。
没有 claude
没有 claude
找到 claude.ps1
若也没有
输入 claude
检查 %PATH% 第 1 项

C:\\Windows\\system32\\
检查 %PATH% 第 2 项

C:\\Program Files\

odejs\\
检查 %PATH% 第 3 项

D:\\software\

odejs\\prefix\\
停止扫描，执行它
报错：无法识别的命令

关键特性：

PATH 从左到右按顺序扫描，第一个找到就停止
当前工作目录与命令查找无关，所以你在任何文件夹都能执行 claude
若两个目录都有同名命令，PATH 中靠前的那个优先

查看当前 PATH：

powershell 复制代码

$env:PATH -split ";"   # PowerShell，每行一个目录

plain 复制代码

echo %PATH%            # cmd

PATHEXT：Windows 独有的扩展名优先级

Linux/macOS 只要文件有执行权限就能运行，Windows 额外用 %PATHEXT% 决定尝试扩展名的顺序：
不存在
不存在
不存在
claude.cmd 存在
在目录中搜索 claude
尝试 .COM
尝试 .EXE
尝试 .BAT
尝试 .CMD
执行 claude.cmd

五、完整执行链路（PowerShell 输入 `claude`）

把所有环节串联起来：
① 你在任意目录输入 claude
② PowerShell 检查内置命令

cd, ls, echo... 均无 claude
③ 按 %PATH% 顺序扫描

在 D:\\software\

odejs\\prefix\\ 找到 claude.ps1
④ 执行 claude.ps1

& node '...cli.js' $args
⑤ 通过 PATH 找到 node.exe

D:\\software\

odejs\

ode.exe
⑥ node.exe 加载 cli.js

@anthropic-ai\\claude-code\\cli.js
⑦ Claude Code 启动完成

进入交互界面

六、PATH 的两个层级

用户 PATH（仅当前用户）
自动写入
修改
系统 PATH（所有用户生效，需管理员）
C:\\Windows\\system32
C:\\Program Files\

odejs
D:\\software\

odejs\\prefix
其他用户自定义目录...
npm install -g
npm config set prefix

系统 PATH：对所有用户生效，修改需要管理员权限
用户 PATH ：仅当前用户，npm install -g 后自动将 prefix 目录加入，无需手动配置

七、`.claude` 用户数据目录

程序代码装在 node_modules 里，但 Claude Code 运行时产生的所有用户数据都存放在另一个完全独立的目录：

plain 复制代码

C:\Users\<用户名>\.claude\

两个目录的职责对比

覆盖更新 ✅
完全不影响 🔒
💾 用户数据（读写）

C:\\Users\\15028\\.claude\\
settings.json --- 配置
history.jsonl --- 对话历史
plugins\\ commands\\ --- 扩展
projects\\ todos\\ --- 项目数据
📦 程序代码（只读）

node_modules\\@anthropic-ai\\claude-code\\
cli.js --- 程序入口
src\\ dist\\ --- 所有功能源码
package.json --- 版本与依赖
npm update / npm uninstall

npm update 只更新程序代码，用户数据完全不受影响
卸载 Claude Code 后，.claude 目录依然保留，重装后历史记录和配置全部恢复

目录内各文件详解

配置文件

文件	作用
`settings.json`	主配置，存模型选择、主题、快捷键等全局设置

子目录
.claude\\
cache\\ --- 请求缓存，加速重复调用
commands\\ --- 用户自定义斜杠命令
plugins\\ --- 插件扩展
projects\\ --- 各项目独立上下文和配置
todos\\ --- 任务列表持久化
file-history\\ --- 文件修改历史，支持撤销
paste-cache\\ --- 粘贴内容临时缓存
backups\\ --- 自动备份
debug\\ --- 调试日志
ide\\ --- VS Code 等 IDE 集成状态
session-env\\ --- 会话环境变量快照
shell-snapshots\\ --- shell 状态快照
statsig\\ --- 功能开关与 A/B 测试配置
telemetry\\ --- 使用统计遥测数据

八、快速验证命令

powershell 复制代码

# 找到 claude 命令的完整路径
where.exe claude

# 查看入口脚本内容
Get-Content "D:\software\nodejs\prefix\claude.ps1"

# 查看 npm 全局配置
npm config get prefix
npm root -g

# 查看完整 PATH（每行一个目录）
$env:PATH -split ";"

总结

概念	一句话解释
Node.js	JavaScript 的运行时，Claude Code 的"发动机"
npm	Node.js 的包管理器，负责安装和管理依赖
prefix 目录	npm 全局包的安装根目录，可自定义到任意位置
`.cmd` / `.ps1`	npm 自动生成的跳板脚本，最终都调用 node 执行 js
PATH	系统查找命令的有序目录列表，决定 `claude` 能否被找到
PATHEXT	Windows 专有，决定无扩展名命令尝试哪些后缀
cli.js	Claude Code 真正的程序入口，由 node.exe 执行
`.claude\`	用户数据目录，存配置、历史、插件，升级卸载不影响
`settings-xxx.json`	多模型配置文件，支持切换不同 AI 后端
`history.jsonl`	所有对话历史，JSONL 格式持久化存储

【深度解析】从 claude 命令到 cli.js 的完整执行链路

【解析】从 claude 命令到 cli.js 的完整执行链路

一、整体架构：三层结构

二、npm 全局安装后的文件结构

全局目录在哪里？

实际目录结构

为什么每个命令有三个入口文件？

三、入口脚本内容解析

四、PATH 环境变量工作机制

PATHEXT：Windows 独有的扩展名优先级

五、完整执行链路（PowerShell 输入 claude）

六、PATH 的两个层级

七、.claude 用户数据目录

两个目录的职责对比

目录内各文件详解

八、快速验证命令

总结

【解析】从 `claude` 命令到 `cli.js` 的完整执行链路

五、完整执行链路（PowerShell 输入 `claude`）

七、`.claude` 用户数据目录