企业官网建设流程全解析

1. 为什么要在 Windows 上认真折腾 Claude Code

很多人第一次听到 Claude Code，第一反应是"这不就是个命令行里的 AI 助手吗，装一下不就行了"。真上手才发现，Windows 上的坑比想象中多得多：Node 版本不对、npm 全局路径带空格、终端权限不够、VS Code 插件和 CLI 各跑各的、本地模型接不进来、脚本一执行窗口就闪退。我自己前前后后在三台不同配置的 Windows 机器上装过，从 Win10 21H2 到 Win11 23H2，踩的坑基本能凑成一本小册子。

这篇东西就是把这套流程完整捋一遍。核心关键词是Windows、Claude Code、安装配置、避坑优化，目标读者是两类人：一类是刚接触命令行 AI 工具、想在自己 Windows 电脑上跑起来的新手；另一类是已经装过但总在各种报错里打转、想搞清楚"为什么这么配"的老手。我会从环境准备讲到安装、配置、VS Code 集成、本地模型对接，再到常见报错排查，每一步都说明白背后的逻辑，而不是甩几条命令让你照抄。

先说清楚 Claude Code 是什么。它是 Anthropic 推出的一个命令行形态的编程助手，运行在终端里，能读你当前项目的文件、执行命令、改代码、跑测试，本质上是把大模型能力直接嵌进你的开发工作流。它和网页版对话最大的区别在于"有手有脚"——能直接操作你的文件系统和终端。这也是为什么安装配置比普通 npm 包麻烦：它需要和你的 shell、Node 运行时、权限体系深度打交道，而 Windows 的终端生态恰恰是这三样里最碎的一环。

适合谁看？如果你日常用 Windows 做开发，主力编辑器是 VS Code，偶尔想接本地模型省钱或者做离线实验，那这篇基本能覆盖你 90% 的场景。如果你只是想随便试试，那至少把第 2 章的环境准备看完，能帮你省掉后面一大半的报错。

2. 装之前必须搞定的环境底座

2.1 Node.js 版本选择与安装方式

Claude Code 是 npm 包，所以 Node.js 是硬依赖。这里第一个坑就是版本。官方要求 Node 18 以上，但我实测下来，Node 20 LTS 是最稳的，Node 22 也能跑，但个别依赖在 22 上偶发兼容问题。别用奇数版本（19、21），那些是非 LTS，生命周期短，出问题没人管。

安装方式我强烈建议用nvm-windows而不是官网直接下 msi。原因很简单：你以后大概率会遇到"这个项目要 Node 18，那个工具要 Node 20"的情况，用 nvm 一条命令就能切，不用卸载重装。nvm-windows 的安装包在 GitHub 上，装完之后用管理员权限开一个新的 PowerShell，执行：

nvm install 20.18.0 nvm use 20.18.0 node -v npm -v

看到版本号输出就说明成了。这里有个细节：nvm-windows 切换版本后，必须重开终端才生效，因为环境变量是在终端启动时读取的。我第一次装的时候切完版本发现还是老版本，折腾了半小时才发现是这个原因。

注意：如果你之前用官网 msi 装过 Node，装 nvm-windows 之前一定要先把原来的卸载干净，并且手动检查C:\Program Files\nodejs和用户目录下的AppData\Roaming\npm是否残留，否则两个 Node 会打架，where node会输出两条路径。

2.2 npm 全局路径与权限问题

Windows 上 npm 全局安装默认往C:\Users\你的用户名\AppData\Roaming\npm里塞，这个路径本身没问题，但如果你开了 OneDrive 同步用户目录，或者用户名带中文、带空格，就会出幺蛾子。Claude Code 安装后生成的启动脚本里会硬编码这个路径，一旦路径里有空格，脚本解析就会断。

我的做法是把 npm 全局目录挪到一个纯英文无空格的路径，比如D:\dev\npm-global：

npm config set prefix "D:\dev\npm-global" npm config set cache "D:\dev\npm-cache"

设完之后把D:\dev\npm-global加到系统 PATH 里。这一步做完，后面装 Claude Code 基本不会遇到路径相关的报错。另外记得用管理员权限开终端做全局安装，否则可能因为权限不足写不进去。

2.3 终端选择：别用老 cmd

Claude Code 在终端里跑，终端选不对体验差一大截。老版 cmd.exe 直接排除，它不支持 ANSI 转义序列，Claude Code 的输出会变成一堆乱码方块。推荐两个：

• Windows Terminal：微软官方的现代终端，支持多标签、分屏、字体渲染好，Win11 自带，Win10 去商店装。
• Git Bash：如果你习惯 Unix 命令，这个也行，但要注意它和 PowerShell 的环境变量读取逻辑不一样。

我主力用 Windows Terminal + PowerShell 7。PowerShell 7 比自带的 5.1 强很多，尤其在处理 UTF-8 编码上。装完 PowerShell 7 后，在 Windows Terminal 里把它设为默认 profile。

提示：不管用哪个终端，都建议把编码设成 UTF-8。PowerShell 里执行[Console]::OutputEncoding = [System.Text.Encoding]::UTF8，或者直接在 profile 文件里写死，否则中文输出会乱码。

2.4 Git 的安装与基础配置

Claude Code 很多操作依赖 Git，比如它要读你的仓库状态、看 diff。Git for Windows 装的时候有个选项叫 "Use Git from the Windows Command Prompt"，建议选上，这样 Git 会把自己的路径加进 PATH。装完配置一下身份：

git config --global user.name "你的名字" git config --global user.email "你的邮箱" git config --global core.autocrlf true

core.autocrlf true这个在 Windows 上很关键，它负责在提交时把 CRLF 转成 LF，避免和 Linux 协作者产生一堆换行符 diff。这个坑我在团队协作时踩过，一个文件改一行结果整个文件都显示改动，就是换行符闹的。

3. Claude Code 的安装与首次配置

3.1 安装命令与验证

环境齐了之后，安装本身就一条命令：

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

装完执行claude --version，能输出版本号就说明二进制装好了。如果报 "command not found"，八成是 npm 全局路径没进 PATH，回去检查 2.2 那步。

第一次运行claude会引导你登录。它会打开浏览器让你授权，授权完把 token 粘回终端。这里有个常见问题：浏览器授权后回调失败。原因通常是默认浏览器和终端不在同一个用户会话，或者公司网络拦截了回调。解决办法是手动复制终端里给出的 URL 到浏览器打开，授权后手动把 code 粘回去。

3.2 配置文件的位置与结构

Claude Code 的配置分两层：全局配置在用户目录下的.claude文件夹，项目级配置在项目根目录的.claude文件夹。全局配置管账号、默认模型、全局权限；项目配置管这个项目特有的规则，比如允许执行哪些命令、忽略哪些文件。

全局配置文件大概是这样的结构：

{ "model": "claude-sonnet-4-5", "permissions": { "allow": ["Bash(git status)", "Bash(npm test)"], "deny": ["Bash(rm -rf *)"] } }

permissions这块是重点。Claude Code 默认每次要执行命令都会问你，你可以把常用的只读命令加进 allow 列表，减少打断。但千万别图省事把Bash(*)全放开，那等于给它无限权限，一个误操作就能删你半个项目。我的原则是：只读命令放开，写操作和删除操作一律手动确认。

3.3 模型选择与 API 配置

默认用的是 Anthropic 官方模型。如果你有 API key，可以在配置里指定。这里要区分两种接入方式：一种是官方 API，一种是走兼容层接第三方或本地模型。官方 API 最省心，配置里填 key 就行。

如果你所在的环境访问官方接口不稳定，或者想省钱用本地模型，那就需要走兼容层，这个在第 5 章详细讲。这里先记住一点：模型配置是可以按项目覆盖的，你可以在某个项目里用本地小模型做简单任务，在另一个项目里用官方大模型做复杂重构，互不影响。

注意：API key 不要硬编码在会提交到 Git 的配置文件里。用环境变量ANTHROPIC_API_KEY，或者放在全局配置里并确保.claude目录在.gitignore中。

4. VS Code 集成：让 Claude Code 真正好用起来

4.1 插件安装与 CLI 的关系

很多人以为 VS Code 里的 Claude Code 插件是独立的一套东西，其实不是。插件本质上是 CLI 的图形化外壳，它调用的是你系统里装的那个claude命令。所以如果你 CLI 没装好，插件也用不了。这个认知很重要，能帮你理清排查思路：插件出问题，先回终端跑claude看正不正常。

在 VS Code 扩展市场搜 "Claude Code" 装上，装完在设置里确认 CLI 路径。如果它自动检测不到，手动填你 npm 全局目录下的claude.cmd完整路径。

4.2 在编辑器里调用终端命令的正确姿势

插件装好后，你可以直接在 VS Code 里开一个 Claude Code 面板，它会以当前打开的文件夹为工作目录。这里有个体验上的关键点：工作目录决定了它能读到哪些文件。如果你打开的是一个大 monorepo 的根目录，它扫描起来会很慢，而且容易读到不相关的文件。建议直接打开你要改的那个子项目文件夹。

调用终端命令时，插件会把命令发给 CLI 执行，结果回显在面板里。我实测下来，涉及文件改动的操作在插件里确认起来比纯终端舒服，因为能直接看到 diff 高亮。

4.3 常见集成报错与解决

最常见的报错是error: start the windows daemon from a non-elevated terminal; shared clients。这个报错的意思是：你之前用管理员权限启动过 Claude Code 的后台守护进程，现在用普通权限的终端去连，权限不匹配，连不上。

解决办法有两个：一是统一权限，要么都用管理员，要么都用普通用户，别混着来；二是杀掉残留的守护进程再重开。在任务管理器里找claude相关的进程结束掉，或者用命令：

taskkill /F /IM claude.exe

然后重开终端。这个坑我遇到过一次，当时以为是插件坏了，重装了三遍插件都没用，最后发现是权限不一致。

另一个常见问题是 VS Code 里终端能跑claude，但插件面板报找不到命令。这通常是 VS Code 启动时继承的 PATH 和你手动开终端时的 PATH 不一样。解决办法是完全重启 VS Code（不是重载窗口，是彻底退出再开），让它重新读取系统环境变量。

5. 接入本地模型：用 LM Studio 跑离线推理

5.1 为什么要在本地跑模型

接本地模型主要有三个理由：省钱、离线可用、数据不出本机。对于日常的代码补全、简单重构、写注释这类任务，本地跑个 7B 到 14B 的模型完全够用，没必要每次都调云端大模型。LM Studio 是目前 Windows 上最省心的本地模型运行工具，图形界面，一键下载模型，自带兼容 OpenAI 格式的 API 服务。

5.2 LM Studio 的部署与 API 开启

去 LM Studio 官网下 Windows 版装上，在模型搜索里找量化版本（GGUF 格式），比如 Qwen 系列的 coder 版本。下载完在 "Local Server" 标签页点启动，默认监听http://localhost:1234。启动后它会暴露一个和 OpenAI API 兼容的接口，路径是/v1/chat/completions。

关键参数是上下文长度。默认可能只有 4096，跑代码任务不够用，建议在加载模型时把 context length 调到 8192 或更高，具体看你显存。显存不够就调小，或者用量化程度更高的模型（Q4 比 Q8 省显存但精度略降）。

5.3 让 Claude Code 指向本地端点

Claude Code 支持通过环境变量指定 API 端点。设置：

set ANTHROPIC_BASE_URL=http://localhost:1234/v1 set ANTHROPIC_API_KEY=lm-studio

API key 随便填，LM Studio 不校验。然后在 Claude Code 配置里把模型名改成你 LM Studio 里加载的模型标识。这样它就会把请求发到本地。

注意：本地小模型在工具调用（tool use）上的能力普遍弱于云端大模型，可能出现"该执行命令时不执行"或者"参数格式错"的情况。我的经验是，本地模型适合做问答和代码解释，涉及多步工具调用的复杂任务还是交给云端模型。

5.4 本地模型的性能调优

影响本地推理速度的主要是显存和量化等级。给你一个参考：14B 的 Q4 量化模型大概需要 10GB 左右显存，7B 的 Q4 大概 5GB。如果你的显卡显存不够，LM Studio 会回退到 CPU 推理，速度会慢到没法用。

调优的几个方向：一是开启 GPU 层数最大化，在 LM Studio 里把 GPU offload 层数拉满；二是用更小的量化，Q4_K_M 是速度和质量的平衡点；三是控制上下文长度，上下文越长显存占用越大，够用就行别贪多。

6. 避坑优化：那些文档里不会写的经验

6.1 权限与守护进程的坑

前面提过的non-elevated terminal报错，根源是 Windows 的权限隔离。Claude Code 在后台跑了个守护进程来维持会话，这个进程的权限级别取决于你第一次启动它时的终端权限。之后所有连接都必须匹配这个级别。

我的建议是固定用普通用户权限，别用管理员。因为管理员权限下 Claude Code 能改系统文件，风险太大。如果你不小心用管理员启动过，记得把守护进程杀掉重来。检查方法是在任务管理器里看有没有claude进程，有就结束掉。

6.2 脚本闪退与编码问题

Windows 上跑.cmd或.bat脚本经常一闪而过，看不到报错。这是因为脚本执行完窗口就关了。解决办法是在脚本末尾加pause，或者从已经打开的终端里手动执行脚本，这样报错会留在屏幕上。

编码问题也很常见。Windows 默认代码页是 GBK，而 Claude Code 输出的是 UTF-8，两者不匹配就乱码。除了前面说的设终端编码，还可以在系统设置里把"Beta: 使用 Unicode UTF-8 提供全球语言支持"打开，一劳永逸。但这个选项会影响一些老程序，开之前想清楚。

6.3 网络与代理相关的稳定性

如果你在公司网络环境，可能会遇到 API 请求超时。这时候需要配置代理。Claude Code 会读HTTPS_PROXY环境变量：

set HTTPS_PROXY=http://你的代理地址:端口

设完重开终端生效。注意代理地址别写错协议头，http 和 https 要分清。另外如果代理需要认证，格式是http://用户名:密码@地址:端口。

6.4 常见问题速查表

6.5 我个人的几条硬核心得

第一，环境隔离。别把 Claude Code 装在系统全局环境里和一堆其他工具混着，用 nvm 管 Node，用独立目录管 npm 全局包，出问题好排查也好清理。

第二，权限最小化。allow 列表只放只读命令，写操作一律确认。我见过有人图省事全放开，结果模型理解错意图执行了个批量删除，虽然最后从 Git 恢复了，但吓出一身冷汗。

第三，配置版本化。把项目级的.claude配置提交到仓库，团队共享同一套规则，避免每个人行为不一致。全局配置里的敏感信息用环境变量，别提交。

第四，本地模型当补充不当主力。本地模型适合快速问答和离线场景，复杂任务还是云端模型靠谱。两者结合用，成本和体验都能兼顾。

第五，遇到报错先看日志。Claude Code 的日志在用户目录的.claude文件夹下，很多报错终端只显示一行，日志里才有完整堆栈。养成看日志的习惯，排查效率翻倍。

这套流程我在三台机器上验证过，从零到能用大概 20 分钟，其中大部分时间花在下载 Node 和模型上。真正配置的时间也就几分钟。关键是把环境底座打牢，后面基本不会出问题。如果你卡在某一步，对照第 6 章的速查表先自查，八成能自己解决。