Claude Code 报错 "process exited with code 1" 排查指南

process exited with code 1 是一个通用退出码，本身不携带具体错误信息，只说明"进程在完成任务前异常终止"。原因可能出在鉴权、Node 环境、MCP 配置、网络或文件权限等任一环节。本文按从高频到低频的顺序给出排查步骤。

第一步：优先用官方内置诊断工具

在手动排查前，先跑一遍官方自带的诊断命令，能覆盖大部分场景：

bash

# 如果 Claude Code 还能启动，在会话内运行
/doctor

# 如果 claude 命令完全启动不起来，在终端里运行
claude doctor

它会自动检查安装状态、版本、配置文件是否合法、MCP 服务器状态、网络连通性等，并给出具体问题定位，比逐条排查更快。

常见原因排查

1. API Key 未配置或已失效（最高频）

典型报错：

Error: Authentication failed
process exited with code 1

先确认环境变量是否设置：

bash

# 检查 API Key
echo $ANTHROPIC_API_KEY

# 若通过第三方中转服务接入，检查 BASE_URL 是否正确
echo $ANTHROPIC_BASE_URL

写入 shell 配置文件（~/.bashrc 或 ~/.zshrc）：

bash

export ANTHROPIC_API_KEY="sk-ant-xxxxxx"
export ANTHROPIC_BASE_URL="https://你的中转地址"   # 使用官方 API 则不需要设置这一项

source ~/.zshrc  # 立即生效

若使用订阅账号（Pro/Max/Team）通过 OAuth 登录，注意 ANTHROPIC_API_KEY 一旦被设置会覆盖 OAuth 凭证，导致登录后依然鉴权失败。这种情况下取消该环境变量，重新执行 claude（或 claude /login）走 OAuth 流程即可。

若使用 .env 文件管理变量，注意：

该文件需放在 Claude Code 的启动目录下才会被读取；
等号两侧不要留空格（KEY=value，不是 KEY = value）。

2. Node.js 版本过低（仅影响 npm 安装方式）

bash

node --version

若通过 npm install -g @anthropic-ai/claude-code 安装：Node.js 版本过低会导致模块加载失败或语法错误。早期版本要求 ≥18.x，但新版 npm 包（v2.1.198 起）已要求 Node.js 22 及以上，版本过低时 npm 会打印 EBADENGINE 警告。
若通过官方原生安装脚本（macOS/Linux 的 curl 一键安装、Windows 的 PowerShell 安装命令）或 Homebrew 安装：不依赖本机 Node.js，因为它直接下载独立的原生二进制文件。如果你不想折腾 Node 版本，优先用原生安装方式。

用 nvm 升级 Node 并重装（npm 安装路径适用）：

bash

nvm install 22
nvm use 22
nvm alias default 22

npm install -g @anthropic-ai/claude-code

3. MCP 配置文件格式或路径错误

配置过 MCP 扩展后，JSON 格式错误（多一个逗号、少一个引号）是高频问题。

典型报错：

Failed to parse MCP config
process exited with code 1

正确的配置文件位置（注意：不是 mcp_settings.json，这是一个常见的误传）：

~/.claude.json        # 用户级 / 本地级配置（跨项目 或 单项目私有）
.mcp.json             # 项目级配置，位于项目根目录，可提交到 git 与团队共享

推荐用官方命令添加，而不是手写 JSON：

bash

# 添加一个 stdio 类型的 MCP 服务器（本地私有，默认作用域）
claude mcp add my-server -- npx -y @modelcontextprotocol/server-filesystem /tmp

# 添加到项目级配置，供团队共享
claude mcp add --scope project my-server -- npx -y some-mcp-server

# 添加到用户级配置，跨所有项目生效
claude mcp add --scope user my-server -- npx -y some-mcp-server

若手动编辑了配置文件，改完先用 Python 校验一遍 JSON 格式：

bash

cat ~/.claude.json | python3 -m json.tool
# 或
cat .mcp.json | python3 -m json.tool
# 有语法错误会直接报出具体是哪一行

配置完成后，在会话内运行 /mcp 检查各 MCP 服务器的连接状态。

4. 网络连不上（代理或防火墙）

网络环境下常见。

bash

# 测试 API 端点是否可达
curl -I https://api.anthropic.com

# 检查当前代理设置
echo $https_proxy
echo $http_proxy

修复方式：

bash

# 方式一：开启代理
source /etc/waas-script/proxy.sh

# 方式二：使用第三方中转 API（企业内网常用，免代理）
export ANTHROPIC_BASE_URL="https://你的中转地址"

5. 文件权限不足

Claude Code 在生成代码或修改文件时，若目标目录无写权限，同样会以 code 1 退出。

bash

# 检查当前目录权限
ls -la .

# 检查 npm 全局目录权限
ls -la $(npm root -g)

修复：

bash

# 修复项目目录权限
chmod 755 ./your-project

# 重新配置 npm 全局目录，避免频繁使用 sudo
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

以上都排查完仍无头绪：开启 Debug 模式

bash

# 启动时开启 debug 模式（终端会打印详细内部日志）
claude --debug

# 会话内临时开启
/debug

# 直接把 debug 日志写入文件（会自动启用 debug 模式，无需再加 --debug）
claude --debug-file ./claude-debug.log

日志中会包含具体的堆栈信息和失败的模块名，通常能一眼看出问题卡在哪一环。

自检脚本

把常见检查项打包成脚本，每次遇到问题先跑一遍：

bash

#!/bin/bash
echo "=== Claude Code 环境自检 ==="

# Node 版本
NODE_VER=$(node --version 2>/dev/null)
echo "Node.js: ${NODE_VER:-未安装（若使用原生安装方式可忽略）}"

# API Key
if [ -n "$ANTHROPIC_API_KEY" ]; then
  echo "API Key: 已设置 (${ANTHROPIC_API_KEY:0:8}...)"
else
  echo "API Key: 未设置（如走 OAuth 登录可忽略）"
fi

# BASE URL
echo "Base URL: ${ANTHROPIC_BASE_URL:-默认 api.anthropic.com}"

# MCP 配置验证（正确路径：~/.claude.json 和 项目根目录下的 .mcp.json）
for MCP_FILE in "$HOME/.claude.json" "./.mcp.json"; do
  if [ -f "$MCP_FILE" ]; then
    python3 -m json.tool "$MCP_FILE" > /dev/null 2>&1 \
      && echo "MCP 配置 ($MCP_FILE): 格式正确" \
      || echo "MCP 配置 ($MCP_FILE): JSON 格式错误"
  fi
done

# 网络连通性
curl -s -o /dev/null -w "%{http_code}" https://api.anthropic.com | grep -q "200\|301\|403" \
  && echo "网络: API 可达" \
  || echo "网络: API 不可达，请检查代理设置"

# 官方诊断工具提示
echo "如需更完整的诊断，请运行: claude doctor"

保存为 check-claude.sh，chmod +x 后随时运行。

排查优先级小结

先运行 claude doctor（或会话内 /doctor），自动覆盖大部分场景
查 API Key / OAuth 冲突，最常见，几秒可确认
查 Node.js 版本（仅 npm 安装方式需要关注；原生安装可跳过）
用 Python 校验 MCP 配置的 JSON（注意正确文件是 ~/.claude.json 和 .mcp.json）
检查网络连通性和代理设置
检查项目目录及 npm 全局目录权限
以上都没问题，开启 claude --debug 查看原始日志

参考资料

官方文档 - Troubleshooting: https://code.claude.com/docs/en/troubleshooting
官方文档 - Debug your configuration: https://code.claude.com/docs/en/debug-your-config
官方文档 - Connect Claude Code to tools via MCP: https://code.claude.com/docs/en/mcp
官方文档 - Advanced setup（系统要求 / 安装方式）: https://code.claude.com/docs/en/setup

Claude Code 报错 "process exited with code 1" 排查指南 ​

第一步：优先用官方内置诊断工具 ​

常见原因排查 ​

1. API Key 未配置或已失效（最高频） ​

2. Node.js 版本过低（仅影响 npm 安装方式） ​

3. MCP 配置文件格式或路径错误 ​

4. 网络连不上（代理或防火墙） ​

5. 文件权限不足 ​

以上都排查完仍无头绪：开启 Debug 模式 ​

自检脚本 ​

排查优先级小结 ​

参考资料 ​

Claude Code 报错 "process exited with code 1" 排查指南

第一步：优先用官方内置诊断工具

常见原因排查

1. API Key 未配置或已失效（最高频）

2. Node.js 版本过低（仅影响 npm 安装方式）

3. MCP 配置文件格式或路径错误

4. 网络连不上（代理或防火墙）

5. 文件权限不足

以上都排查完仍无头绪：开启 Debug 模式

自检脚本

排查优先级小结

参考资料