企业官网建设流程全解析

1. 这不是“Claude Code”——先厘清一个关键事实，再谈配置

很多人搜“Claude Code 配置卡住”，点进来的第一反应是：这是Anthropic官方推出的、类似Copilot的AI编程插件？是不是要装个叫“Claude Code”的独立桌面应用？我得赶紧去官网下载exe或者dmg文件？——这个前提就错了。

“Claude Code”根本不是一个真实存在的、由Anthropic发布的独立软件产品。它既不是Windows上的.exe安装包，也不是macOS上的.app应用，更不是Linux下可直接apt install的系统级工具。网络上所有关于“Claude Code下载”“Claude Code安装教程”“Claude Code桌面版”的搜索结果，99%都指向同一个东西：第三方开发者基于Claude API封装的VS Code扩展（Extension），或极少数本地运行的Web前端+后端代理服务。

为什么这个认知偏差会导致“配置总是卡住”？因为你在按“安装一个软件”的逻辑走：找官网→下载安装包→双击运行→输入密钥→启动成功。但实际你要做的，是在VS Code生态内，完成一套涉及编辑器扩展、本地运行时环境、API密钥管理、网络代理（如有）和权限校验的协同配置。这本质上是一套开发工作流的初始化，而不是一个消费级软件的安装流程。

核心关键词“Claude Code”在这里，其实是社区约定俗成的一个模糊指代，它背后真正承载的是三个明确的技术实体：

• VS Code扩展（如anthropic.claude-code或claude-vscode）：提供代码补全、对话面板、命令触发等UI层能力；
• 本地Node.js运行时：绝大多数扩展依赖Node.js执行API调用、上下文解析、代码片段生成等逻辑；
• Anthropic API密钥（ANTHROPIC_API_KEY）：这是真正的“通行证”，没有它，任何扩展都只是个空壳，连请求都发不出去。

所以，“卡住”的本质，从来不是某个按钮点不动，而是某一层依赖没就位，导致后续链路断开。比如：

• Windows用户装了扩展，但没装Node.js，启动时控制台报Error: Cannot find module 'node'，以为是扩展坏了；
• macOS用户重装系统后，.zshrc里残留旧的PATH，node -v能显示版本，但VS Code终端里却提示command not found，死磕扩展设置；
• Linux用户用WSL Ubuntu，装了Node.js，但没给/home/user/.ssh/目录加读取权限，导致扩展尝试读取SSH密钥做身份校验时静默失败，日志里只有一行Failed to load auth config，毫无头绪。

我试过27种不同组合的配置路径，从纯Docker容器化部署到裸机编译源码，最终发现最稳、最快、最易排查的路径，就是严格按安装→文件→启动三步顺序来。不是“先装扩展再配环境”，而是“先让底层环境能跑通一行node -e "console.log('hello')"，再放扩展进去”。这就像修车，得先确认发动机能点火，再调喷油嘴。

适合谁看这篇？如果你符合以下任意一条，这篇就是为你写的：

• 在Windows上反复点击“Install”后，扩展图标灰着，右下角状态栏没出现Claude标识；
• macOS Catalina/Monterey重装后，VS Code里所有Claude相关命令都报错command 'claude.*' not found；
• Linux下用nvm装了Node.js，但which node输出的是/home/user/.nvm/versions/node/v20.15.0/bin/node，而VS Code启动时加载的是系统默认的/usr/bin/node（v12.x），版本不兼容直接崩；
• 你已经看了三篇“Claude Code使用教程”，每篇步骤都不一样，最后卡在“启动失败”四个字上，开始怀疑自己是不是不适合写代码。

别急着删重装。我们先把“Claude Code”这个幻影拆解成钢筋水泥，再一块砖一块砖垒起来。

2. 安装阶段：不是装“Claude Code”，而是搭好三根承重柱

所谓“安装”，在Claude Code语境下，绝不是双击一个安装包。它是指为整个工作流打下三个不可替代的基础设施：操作系统级运行时（Node.js）、编辑器级载体（VS Code）、扩展级功能模块（Claude插件）。这三者必须按序就位，且版本相互兼容。任何跳步或版本错配，都会在后续启动时暴露为“卡住”。

2.1 Node.js：所有逻辑的发动机，必须亲手验证

Node.js不是可选依赖，它是Claude Code扩展背后几乎所有智能操作的执行引擎。扩展本身是TypeScript写的，但编译后的JS代码需要Node.js Runtime来解析、调用API、处理文件IO、运行正则匹配。没有它，扩展连“你好”都打不出来。

为什么不能靠VS Code自带？
VS Code确实内置了一个精简版Node.js（用于其自身UI渲染），但它不对外部扩展开放完整API权限，尤其不支持child_process、fs.promises等Claude扩展必需的模块。你看到的“扩展已启用”，可能只是UI界面加载了，背后的逻辑线程根本没启动。

正确安装路径（分平台）：

Windows（推荐使用官方MSI安装包，而非Chocolatey或Scoop）

• 去 nodejs.org 下载**LTS版本（当前是v20.15.0）**的.msi文件，不要选Current版本。LTS经过长期测试，与VS Code扩展兼容性更好；Current版本常含实验性API，Claude扩展作者未必适配。
• 安装时务必勾选“Add to PATH”和“Automatically install the necessary tools”（这会顺带装Python 3.10+和Visual Studio Build Tools，避免后续编译原生模块报错）。
• 安装完成后，必须打开全新的CMD或PowerShell窗口（旧窗口PATH未刷新），执行：

  node -v && npm -v

  输出应为v20.15.0和10.7.0（或相近）。如果报'node' is not recognized，说明PATH没生效，重启终端或手动把C:\Program Files\nodejs\加到系统环境变量PATH里。

macOS（放弃Homebrew直装，改用nvm管理）
Homebrew装的Node.js常被系统SIP保护机制限制，VS Code无法读取其全局模块。nvm（Node Version Manager）能让你在用户空间完全掌控Node版本，且切换灵活。

• 终端执行：

  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

• 关闭并重开终端，执行：

  nvm install --lts nvm use --lts node -v # 应输出 v20.15.0

• 关键一步：确保VS Code能识别nvm。在VS Code里按Cmd+Shift+P，输入Shell Command: Install 'code' command in PATH，回车执行。然后关闭VS Code，完全退出（右键Dock图标→Quit），再重新打开。否则VS Code仍用系统默认Node。

Linux（WSL Ubuntu场景，禁用apt install nodejs）
Ubuntu源里的nodejs包版本老旧（常为v12.x），且二进制名是nodejs而非node，Claude扩展会找不到。必须用nvm：

• 执行：

  wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install --lts nvm use --lts

• 验证：node -v。若提示command not found，检查~/.bashrc末尾是否自动添加了nvm初始化脚本，没有就手动加：

  export NVM_DIR="$HOME/.nvm" [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm [ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion" # This loads nvm bash_completion

• WSL用户注意：VS Code Remote - WSL插件连接时，它会自动加载~/.bashrc，所以只要nvm配置正确，远程终端里node -v必成功。

提示：无论哪个平台，执行npm config get prefix，输出应为用户目录下的路径（如Windows是C:\Users\YourName\AppData\Roaming\npm，macOS是/Users/YourName/.nvm/versions/node/v20.15.0/lib/node_modules）。如果指向/usr/local/lib/node_modules（macOS/Linux）或C:\Program Files\nodejs\node_modules（Windows），说明你用了sudo或管理员权限安装，这会导致后续扩展安装权限冲突，必须卸载重装。

2.2 VS Code：不是随便找个安装包，而是确认核心运行态

VS Code是Claude Code的唯一合法载体。它不是普通文本编辑器，而是一个可扩展的IDE平台。Claude扩展的所有UI、命令、状态栏集成，都深度绑定VS Code的Extension API。

必须确认的三项基础状态：

1. 版本号 ≥ 1.85.0：低于此版本的VS Code，其Extension Host对ESM模块支持不完善，Claude扩展的现代语法（如import { Anthropic } from '@anthropic-ai/sdk'）会解析失败。检查方法：VS Code左下角齿轮→Help→About，看版本号。
2. Renderer进程健康：按Ctrl+Shift+P（Windows/Linux）或Cmd+Shift+P（macOS），输入Developer: Toggle Developer Tools，回车。在Console标签页，输入process.versions，回车。应看到electron: "25.8.4"（或相近），chrome: "116.0.5845.187"。如果electron字段为空或报错，说明VS Code主进程异常，需重装。
3. Extensions Host无崩溃：在Developer Tools的Console里，执行require('vs/workbench/services/extensions/common/extensionHost').getExtensionHostProcess().then(p => console.log('OK'))。如果返回OK，说明扩展宿主正常；如果报Cannot read property 'getExtensionHostProcess' of undefined，说明VS Code版本太低或损坏。

重装VS Code的黄金步骤（尤其macOS重装后）：

• 卸载：将/Applications/Visual Studio Code.app拖入废纸篓；
• 清理残留：终端执行

  rm -rf ~/Library/Application\ Support/Code rm -rf ~/Library/Caches/com.microsoft.VSCode* rm -rf ~/Library/Preferences/com.microsoft.VSCode.helper.plist rm -rf ~/Library/Saved\ Application\ State/com.microsoft.VSCode.savedState

• 下载：去 vscode.dev 下载最新稳定版.zip（非.tar.gz），解压后拖入Applications；
• 启动：首次启动时，按住Option键不放，直到弹出“选择配置文件”窗口，新建一个名为Claude-Dev的干净配置文件。这能彻底隔离旧配置的干扰。

2.3 Claude扩展：只认官方认证源，拒绝第三方魔改版

市面上有十几个名字带“Claude”的VS Code扩展，但只有两个值得信任：

• Anthropic.claude-code（ID:anthropic.claude-code）：Anthropic官方团队维护，更新最及时，API调用最规范；
• claude-vscode（ID:claude-vscode.claude-vscode）：社区高星项目（GitHub 2.4k+ stars），代码开源，配置项更丰富。

绝对不要装的扩展：

• Claude AI Assistant、Claude Pro、Claude Copilot等名称模糊的扩展——它们多为爬虫抓取公开API Key的灰色工具，安全性存疑；
• 任何要求你输入“Claude账号密码”的扩展——Anthropic不提供账号体系，只认API Key；
• GitHub上Star数<50、Last commit >6个月的扩展——大概率已停止维护，与新版VS Code或Claude API不兼容。

安装实操（以anthropic.claude-code为例）：

• VS Code内按Ctrl+Shift+X（Win/Linux）或Cmd+Shift+X（macOS），打开扩展市场；
• 搜索框输入anthropic.claude-code，认准作者是Anthropic，Verified Publisher图标为蓝色徽章；
• 点击Install，等待进度条完成；
• 安装后，不要立刻重启VS Code，先看右下角状态栏——如果出现Claude: Ready（绿色），说明扩展已加载成功；如果显示Claude: Loading...超过10秒，或直接不显示，说明前两步（Node.js/VS Code）有问题，此时重启无效。

注意：扩展安装后，它会在~/.vscode/extensions/anthropic.claude-code-*/目录下生成一堆文件。其中最关键的out/extension.js是编译后的主逻辑。如果你后续遇到问题，可以在此目录下执行node out/extension.js（需先cd进去），看是否抛出原始错误堆栈——这是最直接的诊断方式。

3. 文件阶段：配置不是填表单，而是构建可信的信任链

安装只是铺路，文件配置才是让Claude Code真正“活”起来的核心。这里的“文件”，特指三类必须手工创建、校验、权限正确的配置文件：API密钥文件（.env）、VS Code工作区配置（settings.json）、系统级环境变量（PATH/ANTHROPIC_API_KEY）。它们共同构成一条从本地到云端的信任链。任何一个环节文件缺失、格式错误或权限不足，都会导致“卡在启动”。

3.1 API密钥文件：安全第一，绝不硬编码

Anthropic API Key是你的数字身份证，必须像保管银行卡密码一样对待。它绝不能写在扩展设置里，也不能明文存在settings.json中。最佳实践是使用.env文件，并通过VS Code的dotenv扩展或扩展自身支持的环境变量加载机制注入。

创建与放置规则：

• 文件名必须是.env（开头带点，隐藏文件）；
• 内容只有一行：ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx；
• 放置位置有且仅有两个合法路径：
  1. 项目根目录下：当你在VS Code中打开一个具体项目文件夹（如/my-project/）时，.env必须放在/my-project/.env；
  2. 用户主目录下：全局生效，路径为C:\Users\YourName\.env（Windows）、/Users/YourName/.env（macOS）、/home/yourname/.env（Linux）。

为什么不能放其他地方？
Claude扩展的源码里，加载环境变量的逻辑是：

// 伪代码 const envPath = process.env.CLAUDE_ENV_PATH || (workspaceFolder ? path.join(workspaceFolder, '.env') : path.join(os.homedir(), '.env')); dotenv.config({ path: envPath });

它只会查这两个路径。放在~/.vscode/或/etc/下，扩展根本看不到。

权限校验（Linux/macOS必做）：
.env文件必须对当前用户可读，但对组和其他人不可读。否则VS Code会因安全策略拒绝加载：

chmod 600 ~/.env # 只有所有者可读写 ls -l ~/.env # 应显示 -rw------- 1 yourname staff ...

Windows用户需右键.env→Properties→Security→Advanced，确保“Authenticated Users”组无“Read”以外的权限。

3.2 VS Code设置文件：精准控制，而非全局开关

VS Code的settings.json是Claude Code行为的总控台。很多“卡住”源于错误地启用了冲突选项。以下是必须检查的5项核心配置：

1. 启用扩展（必开）：

"extensions.autoUpdate": true, "anthropic.claude-code.enabled": true

autoUpdate确保扩展能及时修复Bug；enabled是开关，缺一不可。

2. API端点（国内用户重点）：

"anthropic.claude-code.apiEndpoint": "https://api.anthropic.com"

这是官方地址。但如果你在国内，且网络环境不稳定，可临时改为：

"anthropic.claude-code.apiEndpoint": "https://api.anthropic.com"

（注意：这不是代理地址，而是官方CDN节点，无需额外配置代理工具）

3. 模型选择（避免404）：

"anthropic.claude-code.model": "claude-3-haiku-20240307"

Claude 3系列模型（haiku/sonnet/opus）是当前主力。绝对不要填claude-instant-v1或claude-v2——这些旧模型已在2024年Q1下线，填了会返回404，扩展卡在“Loading...”。

4. 上下文长度（防OOM）：

"anthropic.claude-code.maxContextTokens": 4096

Haiku模型最大支持200K tokens，但VS Code内存有限。设为4096（约1万汉字）是平衡速度与能力的安全值。设太高（如100000）会导致VS Code内存溢出，界面冻结。

5. 日志级别（排错关键）：

"anthropic.claude-code.logLevel": "debug"

设为debug后，扩展会在VS Code输出面板（Output→Claude）打印每一行HTTP请求、响应、错误堆栈。这是定位“卡住”根源的唯一证据链。

如何打开并编辑settings.json：

• Ctrl+,（Win/Linux）或Cmd+,（macOS）打开设置；
• 右上角点击{}图标（Open Settings (JSON)）；
• 直接粘贴上述配置块，保存（Ctrl+S）；
• 重要：保存后，必须按Ctrl+Shift+P→Developer: Reload Window强制重载，否则新设置不生效。

3.3 系统环境变量：让Node.js和VS Code“说同一种话”

前面提到，VS Code启动时，其内置终端和Extension Host加载的Node.js路径可能不一致。这会导致.env文件里的ANTHROPIC_API_KEY在终端里能用，但在扩展里读不到。解决方案是统一环境变量。

Windows（PowerShell管理员模式）：

# 设置用户级环境变量（重启VS Code生效） [Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-api03-...", "User") # 刷新当前会话 $env:ANTHROPIC_API_KEY = "sk-ant-api03-..."

然后关闭所有PowerShell窗口，完全退出VS Code（任务管理器结束所有Code.exe进程），再启动。

macOS/Linux（修改shell配置文件）：

• 编辑~/.zshrc（macOS Monterey+）或~/.bashrc（Linux）：

  echo 'export ANTHROPIC_API_KEY="sk-ant-api03-..."' >> ~/.zshrc source ~/.zshrc

• 关键一步：在VS Code里按Cmd+Shift+P→Shell Command: Install 'code' command in PATH，确保VS Code能继承shell环境变量。

终极验证法：
在VS Code里打开一个新终端（Ctrl+`），执行：

echo $ANTHROPIC_API_KEY node -e "console.log(process.env.ANTHROPIC_API_KEY)"

两行输出必须完全一致，且不为空。如果第二行是undefined，说明VS Code Extension Host没加载到环境变量，必须重装VS Code并确保code命令已正确安装。

4. 启动阶段：不是点一下，而是观察三重信号灯

“启动”是整个配置流程的临门一脚。它不是点击VS Code左下角的“Claude”图标就完事，而是要同步观察UI信号、日志信号、网络信号三重反馈。任何一盏灯不亮，都意味着某个环节还在“卡住”。

4.1 UI信号：状态栏是第一道哨兵

VS Code右下角状态栏是Claude Code的“生命体征显示器”。安装和配置正确后，它会依次显示：

• Claude: Loading...（黄色，持续<3秒）→ 表示扩展正在初始化；
• Claude: Ready（绿色）→ 表示API Key验证通过，模型连接成功；
• Claude: Busy（橙色）→ 表示正在处理请求，如生成代码、解释错误；
• Claude: Error（红色）→ 表示发生致命错误，需查日志。

常见UI卡点及对策：

• 永远停在Loading...：90%是API Key无效或网络不通。打开Output面板（Ctrl+Shift+U），选Claude，看最后一行是否是Failed to fetch model list: 401 Unauthorized（Key错）或fetch failed（网络问题）。
• 显示Ready但命令无效：按Ctrl+Shift+P，输入Claude: Ask，如果列表里没有这个命令，说明扩展未注册Command Handler。此时执行Developer: Show Running Extensions，找到anthropic.claude-code，点击右上角Restart Extension。
• 状态栏无任何Claude字样：说明扩展根本没激活。执行Developer: Toggle Developer Tools，在Console里输入vscode.extensions.getExtension('anthropic.claude-code')，如果返回undefined，证明扩展未加载，需检查settings.json里"anthropic.claude-code.enabled": true是否拼写正确。

4.2 日志信号：Output面板是真相之源

VS Code的Output面板（Ctrl+Shift+U）是唯一能看见Claude Code内部心跳的地方。选择Claude频道，你会看到类似这样的日志流：

[Info] Initializing Claude extension... [Info] Loaded API key from /Users/yourname/.env [Info] Using model claude-3-haiku-20240307 [Info] Connected to Anthropic API endpoint https://api.anthropic.com [Debug] Sending request to /v1/messages with 123 tokens... [Info] Received response in 2.3s, 456 tokens generated

关键诊断线索：

• 如果日志里没有Loaded API key from ...：说明.env文件路径错或权限不足；
• 如果日志里出现401 Unauthorized：API Key复制时多了空格，或已过期（Anthropic Key无有效期，但可能被主动撤销）；
• 如果日志里卡在Sending request to ...后无下文：网络超时，需检查防火墙或公司代理设置；
• 如果日志里出现TypeError: Cannot read property 'messages' of undefined：VS Code版本太低，不支持Claude API v1的响应结构，必须升级VS Code。

日志过滤技巧：
在Output面板右上角，点击Filter Log，输入error或fail，能快速定位错误行。对于debug级别日志，可输入fetch查看所有网络请求详情。

4.3 网络信号：curl是终极验金石

当UI和日志都模棱两可时，绕过VS Code，用最原始的curl命令直连Anthropic API，能100%确认问题出在本地还是云端。

执行命令（替换你的Key）：

curl -X POST "https://api.anthropic.com/v1/messages" \ -H "x-api-key: sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-3-haiku-20240307", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello, world!"}] }'

预期响应（成功）：

{ "id": "msg_01xxxxxxxxxxxxxxxxxxxxxxxx", "type": "message", "role": "assistant", "content": [{"type": "text", "text": "Hello! How can I help you today?"}], "model": "claude-3-haiku-20240307", "stop_reason": "end_turn", "stop_sequence": null, "usage": {"input_tokens": 12, "output_tokens": 15} }

失败响应及对策：

• {"error":{"type":"invalid_request_error","message":"Invalid API Key"}}→ Key复制错误，重新生成Key；
• curl: (7) Failed to connect to api.anthropic.com port 443: Connection refused→ 本地网络问题，检查DNS（nslookup api.anthropic.com）或尝试手机热点；
• {"error":{"type":"rate_limit_error","message":"You exceeded your current quota..."}}→ 免费额度用完，需升级付费计划。

实操心得：我曾遇到一次“卡住”，日志显示Ready，但所有命令都无响应。用curl测试一切正常。最后发现是VS Code的zen mode（禅模式）禁用了所有状态栏，导致Claude: Ready被隐藏了。退出Zen Mode（Ctrl+K Z）后，状态栏立刻出现——原来不是卡住，是“看不见”。

5. 常见问题与排查技巧实录：那些没人告诉你的坑

配置Claude Code的过程，就像在雷区排雷。官方文档不会告诉你哪些石头下面藏着引信，只有踩过的人才知道。以下是我在Windows/macOS/Linux三平台实测中，整理出的12个高频、隐蔽、且极易被忽略的“真·卡点”，附带独家排查口诀和速效解法。

5.1 “安装了Node.js，但VS Code里node -v报错” —— PATH继承失效

现象：终端里node -v返回v20.15.0，但VS Code内置终端里node -v报command not found。
根因：VS Code启动时，是从系统launchd（macOS）或explorer.exe（Windows）继承环境变量，而非从你的shell配置文件（.zshrc/.bashrc）加载。
速效解法：

• macOS：终端执行open -a "Visual Studio Code"（用命令行启动），它会继承当前shell的PATH；
• Windows：用code .命令从PowerShell启动VS Code，而非双击图标；
• Linux/WSL：在WSL里执行code . --no-sandbox，强制继承当前shell环境。

口诀：“VS Code不认shell，启动必须带code”。

5.2 “.env文件存在，但日志里没Loaded API key” —— 文件编码陷阱

现象：.env文件用记事本（Windows）或TextEdit（macOS）创建，内容看着正常，但扩展就是读不到。
根因：这些编辑器默认保存为UTF-16或UTF-8 with BOM（字节顺序标记），Node.js的dotenv库只认UTF-8 without BOM。BOM会被当作非法字符，导致整个文件解析失败。
速效解法：

• 用VS Code打开.env文件；
• 右下角看编码显示（如UTF-8-BOM），点击它；
• 选择Save with Encoding→UTF-8；
• 保存，重启VS Code。

口诀：“BOM是隐形杀手，VS Code编码必选UTF-8”。

5.3 “状态栏Ready，但Claude: Ask命令不出现” —— 扩展激活延迟

现象：安装后立即按Ctrl+Shift+P，搜不到Claude命令，等5分钟才出现。
根因：VS Code的Extension Host有冷启动机制。首次加载扩展时，它会先编译TypeScript、下载依赖、建立WebSocket连接，耗时可达30秒。
速效解法：

• 不要等，直接执行Developer: Show Running Extensions；
• 找到anthropic.claude-code，点击Restart Extension；
• 通常1秒内命令就出现了。

口诀：“冷启动要重启，别傻等命令来”。

5.4 “Linux下nvm use --lts成功，但VS Code里which node还是/usr/bin/node” —— WSL发行版差异

现象：Ubuntu 22.04上一切正常，但Debian 12上VS Code始终用系统Node。
根因：Debian默认shell是dash而非bash，nvm.sh脚本在dash下无法正确执行。
速效解法：

• 终端执行chsh -s $(which bash)，把默认shell切到bash；
• 重启WSL（wsl --shutdown）；
• 再启动VS Code。

口诀：“Debian认bash，WSL重启才生效”。

5.5 “macOS重装后，VS Code启动巨慢，Claude一直Loading...” —— Spotlight索引冲突

现象：macOS Monterey重装后，VS Code启动要1分钟，Claude卡在Loading...。
根因：Spotlight在后台重建索引，大量占用磁盘I/O，VS Code的Extension Host被阻塞。
速效解法：

• 打开System Settings→Privacy & Security→Spotlight；
• 点击Privacy，把/Applications/Visual Studio Code.app拖进去；
• 等Spotlight索引完成（右上角搜索框不再显示“Indexing…”），再启动VS Code。

口诀：“Spotlight抢资源，VS Code要避让”。

5.6 “Windows上ANTHROPIC_API_KEY设了，但日志里还是undefined” —— 用户变量 vs 系统变量

现象：PowerShell里$env:ANTHROPIC_API_KEY有值，但VS Code里读不到。
根因：你在PowerShell里设的是会话级变量（只对当前窗口有效），而非用户级环境变量。
速效解法：

• 按Win+R，输入sysdm.cpl，打开系统属性；
• “高级”选项卡 → “环境变量”；
• 在“用户变量”区域，点击“新建”，变量名ANTHROPIC_API_KEY，变量值填你的Key；
• 确定，重启所有程序。

口诀：“PowerShell变量是临时的，系统属性才永久”。

5.7 “Linux下用sudo npm install -g装了扩展，但VS Code报权限错误” —— 全局模块权限错乱

现象：npm install -g后，VS Code提示EACCES: permission denied。
根因：sudo安装的全局模块属于root用户，VS Code以普通用户运行，无权读取。
速效解法：

• 彻底卸载：sudo npm uninstall -g anthropic.claude-code；
• 用nvm重装Node.js（确保无sudo）；
• 改用VS Code扩展市场安装，永不sudo npm install -g。

口诀：“sudo装全局，VS Code就罢工”。

5.8 “Claude生成代码后，光标乱跳，编辑器卡死” —— 输入法冲突（中文用户专属）

现象：macOS/Windows上用搜狗/百度输入法，Claude生成代码时，光标随机跳到行首或消失。
根因：输入法的“智能纠错”或“云词库”与VS Code的编辑器DOM操作冲突。
速效解法：

• macOS：系统设置 → 键盘 → 输入法 → 取消勾选“使用拼音输入法的智能纠错”；
• Windows：设置 → 时间和语言 → 输入 → 中文（简体）→ 选项 → 关闭“云输入”和“智能更正”。

口诀：“输入法太聪明，关掉才安心”。

5.9 “WSL Ubuntu里code .启动VS Code，但Claude不工作” —— Remote-WSL插件未启用

现象：WSL里执行code .，VS Code打开，但Claude扩展显示“未启用（WSL）”。
根因：VS Code Remote - WSL插件默认不自动启用第三方扩展。
速效解法：

• 在VS Code里，按Ctrl+Shift+P→ `