Claude Code安装与配置完整指南：系统选择、登录验证与配置管理

安装 Claude Code 最容易被忽略的一步，是确认你正在配置哪一个环境。Windows 原生终端、WSL、macOS 和远程服务器可能拥有不同的程序、账户状态与配置文件。先选定项目真正运行的位置，再安装和登录，后续会省去很多重复排查。

确定安装环境与方式

本文面向终端版 Claude Code。原生安装是官方提供的主要路径，也可以选用 Homebrew 或 WinGet。已经通过某种方式安装的用户，先确认现有位置再升级，避免同一台机器上出现多个版本互相遮挡。

macOS、Linux 与 WSL

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell

irm https://claude.ai/install.ps1 | iex

以上命令按系统选择一条。WSL 中使用 Linux 安装方式，并从 WSL 终端启动；不要将 PowerShell 命令粘到 Bash 中。如果组织统一管理软件，使用其允许的分发路径。

使用包管理器

# 已安装 Homebrew 的 macOS
brew install --cask claude-code

# Windows WinGet
winget install Anthropic.ClaudeCode

选择包管理器后，后续也应通过相应管理器维护更新。安装脚本方式与包管理器方式的更新行为不同，排查版本问题时要先确认安装来源。

验证程序，而后验证账户

claude --version
claude doctor

第一条确认程序可以执行；第二条检查安装与设置。它们通过，不代表账号已经具备模型使用权限。进入项目目录后运行 claude，按照界面选择适用的登录方式，再完成一次简短问答。

订阅登录、Console API 以及组织配置属于不同接入路径。不要把另一个服务的 Key 混入当前环境，也不要因为某个环境变量已经存在，就假定它一定是你想用的认证来源。

配置应放在哪一层

• ~/.claude/settings.json：个人在本机多个项目中使用的偏好。
• .claude/settings.json：项目内可审查、可共享的设置。
• .claude/settings.local.json：当前项目中的个人设置；自行创建时应确认未纳入版本控制。
• 组织托管设置：由组织管理，个人配置不能简单覆盖其策略。

初次配置不要追求“大而全”

先通过 /config 调整自己需要的交互选项，再逐项增加配置。JSON 不接受注释和尾部逗号；编辑已有文件时保留其他字段。项目运行方式和测试说明更适合写进 CLAUDE.md，而不是塞进不相关的设置键。

一份项目说明应该包含什么

写清项目用途、主要目录、安装依赖的方法、测试命令和必须遵守的改动限制。每一条都应能在仓库中核查；不要照抄别的项目的构建命令。

四类常见问题的排查顺序

找不到 claude 命令

先重新打开终端，再检查安装是否完成及 PATH。macOS/Linux 可以使用 command -v claude，PowerShell 使用 Get-Command claude 查看实际命中的程序。

版本与预期不同

检查是否同时保留 npm、原生安装或包管理器版本。确认路径后再决定保留哪一种，不要直接删除整个配置目录来处理版本问题。

设置不生效

查看配置层级与组织策略，确认文件是否在当前项目下，并运行诊断检查语法。一次只修改一个选项，避免无法判断覆盖关系。

能启动但请求失败

保留错误原文，再区分认证、模型权限、网络连接或服务限流。若故障发生在命令执行阶段，检查项目工具链，而不是重新安装 Claude Code。

完成安装的验收标准

程序可运行、账户能请求模型、目标项目可读取、设置修改可以验证，这四项都满足后再开始正式任务。最后记录安装来源和版本，以后升级前后对照同一个小任务，就能快速识别异常。