企业官网建设流程全解析

手上同时握着三套 AI 编程助手配置的人，大概都经历过这种场面：上午连的是团队自建的服务端，下午要切回官方额度跑一个长任务，晚上又想用另一家兼容接口压测成本。每次切换，都得打开资源管理器，钻进用户目录下的隐藏文件夹，找到settings.json，把ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN两行改掉，保存，关终端，重开，再敲一句话确认通不通。改一次两次还行，一天改五次就开始出事了——我有一回切完忘了把 token 换回来，用着旧 key 跑了半个下午的请求，日志里一片 401，排查了四十分钟才反应过来是自己手抖。

CC Switch就是冲着这个痛点来的。它是一个开源的桌面小工具，专门用来管理Claude Code、Codex这类命令行 AI 编程助手的配置档案，把"改文件"这件手工活变成"点一下"。这篇内容讲的是它在Windows上的安装与使用全流程：从下载哪个安装包、系统缺什么运行时、配置档案怎么填、切换为什么没生效，一直到备份、团队共享和几个我实打实踩过的坑。适合三类人看：手上有多套 API 配置来回切的、给团队统一发配置的、以及被环境变量优先级坑过一次想彻底搞明白的。完全没接触过命令行助手的新手也能看懂，我会把每一步的"为什么"一起说清楚。

1. 先想明白：你需要的是配置管理器，不是别的东西

1.1 手工维护 settings.json 的真实成本

命令行 AI 助手的配置，本质上就是几个键值对。以 Claude Code 为例，它的用户级配置在C:\Users\<你的用户名>\.claude\settings.json，里面有一个env对象，用来注入环境变量。你想换服务端，改的就是这个对象里的两三个字段。听起来很简单，简单到很多人觉得"我写个记事本快捷方式就够了"。

问题在于三个字：容易错。第一是路径隐藏，.claude是点开头的目录，资源管理器默认不显示隐藏项，新手第一次找它能找十分钟。第二是格式脆弱，JSON 不允许尾随逗号，不允许注释，多打一个逗号整个文件就解析失败，而助手的报错往往只说"配置无效"，不告诉你第几行。第三是状态遗忘，你改完 A 配置去干别的事，第二天回来完全忘了现在跑的是哪一套，直到账单或者报错把你叫醒。

我见过更隐蔽的一种翻车：有人把 key 直接写在系统环境变量里，然后在settings.json里又写了一份，两份不一致。改文件的那一份永远不生效，因为进程启动时读到的系统环境变量优先级更高。他改了三天，一直以为自己改错文件了，实际上是改错地方了。

1.2 CC Switch 的定位：它只写文件，不碰流量

这里有个认知必须先摆正，否则后面很多现象你会理解不了。CC Switch 做的事情非常朴素：它在你本机维护一份"档案列表"，每条档案包含名称、服务端地址、密钥、模型名这些字段；你点"切换"的时候，它把选中那条档案的内容写进对应工具的配置文件里，同时把原来那份备份走。

也就是说，它不参与任何请求转发，不改变你的网络路径，不启动后台服务去拦截流量。它就是一个带界面的、专门管几个 JSON/TOML 文件的编辑器。理解这一点，你就能自己推断出两件事：第一，切换之后必须重启已经在跑的终端进程，因为进程启动时已经把配置读进内存了；第二，如果切换没生效，八成不是工具坏了，而是有更高优先级的配置把它盖住了。

注意：CC Switch 不解决网络连通性问题。它只负责"写对配置"，服务端能不能通、延迟高不高，取决于你填的那个地址本身。

1.3 什么情况下其实不需要它

说句实话，如果你从头到尾只用一套配置，那装它纯属给自己加一层。直接手写一次settings.json，之后别动就行了。同理，如果你本身就是脚本型选手，习惯用 PowerShell 函数一键切换，那自己维护一个switch-profile.ps1也就二十行代码，可控性还更高。

它真正有价值的场景是这三种：配置数量大于等于三、切换频率高于每周一次、需要把配置分发给别人。第三条尤其关键，团队里发配置最怕的就是"你把你那份 settings.json 发我"，因为里面带着 key，一不小心就进了聊天记录和代码仓库。CC Switch 的档案是分开存的，导出模板时可以把密钥字段留空，接收方自己填，这一点比裸发文件安全得多。

2. 动手之前：先搞清楚它到底会动哪些文件

2.1 Claude Code 侧的配置结构

Windows 上 Claude Code 的用户级配置目录是%USERPROFILE%\.claude\，核心文件是settings.json。最小可用结构长这样：

{ "env": { "ANTHROPIC_BASE_URL": "https://your-endpoint.example.com", "ANTHROPIC_AUTH_TOKEN": "sk-你的密钥", "ANTHROPIC_MODEL": "模型别名" } }

三个字段的分工要说清楚。ANTHROPIC_BASE_URL是服务端根地址，填错这个会直接连不上；ANTHROPIC_AUTH_TOKEN是鉴权令牌；ANTHROPIC_MODEL是默认模型，如果你的服务端只支持特定模型别名，这里必须显式指定，否则助手会拿一个服务端不认识的默认名字去请求，报一个看起来毫不相关的错。

除了settings.json，同目录下还可能有settings.local.json（本地覆盖，通常被 gitignore 忽略）和CLAUDE.md（项目指令）。CC Switch 一般只接管settings.json，这也是为什么有时候你切完发现"有些东西没变"——它本来就不负责那些文件。

2.2 Codex 侧的配置结构

如果你的工具列表里还有 Codex 这类助手，它的配置是 TOML 格式，路径在%USERPROFILE%\.codex\config.toml，密钥则单独放在auth.json里。TOML 和 JSON 的区别在于它支持注释、容忍尾逗号，但键名必须严格匹配，多一层少一层表结构都会让它读不出来。

CC Switch 的新版本一般会用两个独立的标签页分别管这两类工具，切换时各写各的，互不干扰。这意味着你可以在 Claude Code 侧挂着团队网关，同时在 Codex 侧挂着个人额度，两个进程互不影响。这个设计挺实用，因为很多人确实是两套工具并行用的。

2.3 一次"切换"背后发生的三件事

把动作拆开看，切换其实包含三步。第一步是快照：把当前配置文件原样复制到工具自己的数据目录里，命名通常是"工具名-时间戳"。第二步是覆写：用选中档案的内容生成新的配置文件，整体替换，不是逐行修改。第三步是标记：在工具内部的数据库或 JSON 里记下"当前激活的是哪一条"，用于界面上那个高亮状态。

第三步最容易被误解。界面上显示"已激活 A 档案"，只代表工具认为它上次写进去的是 A，不代表此刻磁盘上的文件一定是 A 的内容。如果你在切换之后又手动改过一次settings.json，或者被别的软件（比如某个自动同步的网盘客户端、某个配置下发脚本）覆盖过，界面状态就和实际文件脱节了。

提示：动手前先手动把%USERPROFILE%\.claude\settings.json复制一份到桌面，命名成settings.json.bak。这是最便宜的一份保险，三十秒的事，出事时能救命。

3. Windows 上的安装：从下载到第一次启动

3.1 选哪个安装包，以及为什么

项目发布页通常给两种 Windows 包：.msi和.exe（有些版本还会给一个portable免安装版）。我的建议是优先.msi。原因很实际：.msi走标准 Windows Installer 流程，会写注册表、创建开始菜单项、支持"应用和功能"里正常卸载；而单文件.exe在很多情况下是个自解压的绿色包，卸载时容易留下残留目录和开机自启项，下次装新版本还可能冲突。

版本选择上别迷信最新。如果你只是要管两份配置，取一个发布超过两周、issue 区没有大面积"启动闪退"反馈的版本就行。桌面工具这类项目迭代快，新版本引入回归问题的概率不低。我自己的习惯是先在虚拟机或者一个临时用户账户里跑一遍新版本，确认能正常启动、能读到已有配置，再换到主力账户上。

下载时还有个细节：文件体积。正常的安装包在几十兆量级，如果你拿到的是几兆甚至更小的文件，大概率是下载中断或被页面劫持了，重新下。有校验值就核一下，没有的话至少看一眼文件属性里的数字签名。

3.2 SmartScreen 拦一下是正常的

Windows 10/11 对没有广泛下载量的独立开发者程序会弹"Windows 已保护你的电脑"。这不是病毒警报，是信誉度不足的提示。处理方式是点"更多信息"再点"仍要运行"。如果这个按钮是灰的或者根本没有，说明系统策略被组织管控了，那就别硬来，换一台个人设备或者用免安装版放到非受控目录。

3.3 安装完第一次启动：WebView2 是硬依赖

这类工具大多用 Tauri 或 Electron 做外壳，Windows 上会依赖WebView2 运行时。Win11 和较新的 Win10 已经预装，但一些长期没更新的老机器、精简版系统、或者企业镜像里可能是缺失的。症状是：双击图标，进程在任务管理器里闪一下就没了，没有任何报错窗口。

遇到这种情况，先去"设置 → 应用 → 已安装的应用"里搜WebView2，没有就去微软官方页面下 Evergreen 运行时装上。装完重启一次再试。这一条能解决我见过的绝大多数"双击没反应"问题。

3.4 首次启动后的三件事

第一件，确认它能读到你现有的配置。如果你之前手工配过settings.json，打开工具应该能看到一份自动导入的档案，或者至少提示"检测到现有配置"。看不到就说明它读的路径和你配的路径不是一个地方——这在装过多个版本助手、或者用管理员账户装过全局包的机器上很常见。

第二件，把开机自启和托盘行为定下来。我的习惯是开自启、开最小化到托盘、不开启动时自动切换。前两个是为了随时能点，最后一个是因为自动切换会在你不注意的时候把配置改掉，然后在某个需要复现的排查场景里把你搞疯。

第三件，找到它的数据目录并记住位置。一般在%APPDATA%下以应用名命名的文件夹里。这里面存着档案库和历史快照，是你做备份时真正要备份的东西。

4. 建立配置档案：字段怎么填才不出错

4.1 一条档案需要哪些信息

新建档案时，界面会让你填名称、服务端地址、密钥、（可选的）模型名。名称建议用"用途-环境"的格式，比如团队网关-生产、自建节点-测试、官方-个人。别用test1、aaa这种，一周之后你自己都分不清。

服务端地址这一栏是最容易填错的地方，下面单独说。密钥栏要注意：有些工具区分API_KEY和AUTH_TOKEN两种语义，前者走x-api-key头，后者走Authorization: Bearer。填错类型不会报"你填错了"，只会返回 401 或者 403。如果你不确定，就看服务端文档里的示例请求头。

4.2 Base URL 的三个高频错误

错误一：末尾多斜杠。https://api.example.com/和https://api.example.com在多数实现里等价，但有些服务端会拼出//v1/messages这种双斜杠路径然后返回 404。稳妥做法是统一不带末尾斜杠。

错误二：路径层级多一层或少一层。有的服务端根地址就要带上/v1，有的工具会自动补/v1/messages，你提前加上就变成了/v1/v1/messages。判断方法很简单：拿 curl 或者 PowerShell 的Invoke-WebRequest直接打一次，看哪个地址返回 200，就填哪个。

错误三：协议写错。内网自建服务常常是http://而不是https://，工具默认按 https 处理，直接连不上。内网环境这个坑太常见了。

# 快速验证地址是否可用（把 URL 和 KEY 换成你自己的） $headers = @{ "x-api-key" = "sk-你的密钥"; "anthropic-version" = "2023-06-01" } Invoke-WebRequest -Uri "https://your-endpoint.example.com/v1/messages" ` -Method Post -Headers $headers ` -ContentType "application/json" ` -Body '{"model":"你的模型名","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

这段跑通再往工具里填，能省掉大量"到底是配置问题还是服务问题"的扯皮时间。

4.3 切换之后必须做的验证动作

切换完，别急着开新任务。按这个顺序走一遍：关掉所有终端窗口（不是清屏，是关窗口，因为环境变量在当前会话里已经固化了）→ 重新开一个终端 → 敲一句最简单的提问，比如"用一句话说明你现在用的模型"→ 看返回是否正常，顺便确认服务端日志里出现了这次请求。

如果步骤二之后还是旧配置生效，那基本可以确定是环境变量层级的问题，下一节专门讲。

5. 切换了却没生效：三个层级的断点排查

5.1 断点一：环境变量把文件盖住了

这是排在第一位的元凶。Windows 的环境变量有三个层级：系统级（Machine）、用户级（User）、进程级（当前会话）。优先级从低到高，进程级最高。而settings.json里的env注入，本质上是助手进程启动时自己塞进进程环境的，它会不会覆盖已存在的系统变量，取决于具体实现。

现实中的典型场景：你半年前为了应急，在"系统属性 → 环境变量"里加了ANTHROPIC_BASE_URL，后来忘了。现在 CC Switch 怎么写文件都没用，因为进程继承的始终是那个老值。

用这两条命令一次看清楚：

# 查各层级是否残留了同名变量 [Environment]::GetEnvironmentVariable("ANTHROPIC_BASE_URL","Machine") [Environment]::GetEnvironmentVariable("ANTHROPIC_BASE_URL","User") # 看当前会话里实际生效的值 Get-ChildItem Env: | Where-Object { $_.Name -like "ANTHROPIC*" -or $_.Name -like "OPENAI*" }

任何一条有输出，就说明存在覆盖源。处理方式是用setx删掉，或者走图形界面删除：

# 删除用户级变量（删完要重开终端） [Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", $null, "User")

还有一种更隐蔽的残留：PowerShell 配置文件。检查$PROFILE指向的那个脚本里有没有$env:ANTHROPIC_... = "..."这样的行。每次开终端它都会重新设一遍，表现就是"删了环境变量但重开又有"。

5.2 断点二：读的和写的不是同一个目录

机器上装过多个版本助手时，配置目录可能不止一个。比如 npm 全局安装的版本读%USERPROFILE%\.claude\，而某个独立安装包可能读%APPDATA%\下的另一个路径；再比如你曾经用管理员身份跑过一次，Windows 的虚拟化机制可能把写入重定向到了%LOCALAPPDATA%\VirtualStore\下面。

排查方法很土但有效：切换配置之后，直接看目标文件的内容和修改时间。

Get-Item "$env:USERPROFILE\.claude\settings.json" | Select-Object FullName, LastWriteTime Get-Content "$env:USERPROFILE\.claude\settings.json"

如果修改时间是刚才，内容也对，说明文件写成功了，问题在下游（断点一或断点三）；如果时间没变或者内容还是旧的，说明写的位置不对，那就是路径匹配问题，得去工具的设置里确认它认的目标目录。

5.3 断点三：进程没真正重启

Windows 终端有个特点：你在 Windows Terminal 里开多个标签页，它们共享同一个父进程环境。关掉一个标签页再开一个新的，某些情况下新标签页继承的还是旧的父进程环境，配置依然不生效。

最保险的做法是把整个 Windows Terminal 窗口关掉（不是exit退出 shell，是整个窗口关掉），再重新打开。如果是通过 VS Code 的集成终端用的助手，那就得重启 VS Code 本身——集成终端继承的是编辑器的进程环境，光关终端面板不够。

5.4 一个容易忽略的边界：编码问题

settings.json如果被记事本存成带 BOM 的 UTF-8，或者被存成 GBK，某些解析器会读失败并静默回退到默认配置。表现就是"文件看着完全正确，就是不生效"。判断方法是用 PowerShell 读字节看开头有没有EF BB BF：

$bytes = [System.IO.File]::ReadAllBytes("$env:USERPROFILE\.claude\settings.json") ($bytes[0..2] | ForEach-Object { $_.ToString("X2") }) -join ' '

输出EF BB BF就是带 BOM，需要转成无 BOM。CC Switch 自己写出来的文件一般是干净的，但如果你中途用记事本手动编辑过一次，就可能被污染。

6. 把它用成工程化工具：备份、分发与多机同步

6.1 备份要备的是"档案库"，不是配置文件

很多人备份方向搞反了：备份settings.json没用，因为那是切换的产物，随时会被覆盖；真正要备的是 CC Switch 自己的数据目录，里面存着全部档案和历史快照。做法很简单，把那个目录整个复制走，换个机器再放回同样位置，档案就回来了。

我自己的习惯是每次大改档案之前手动导出一份，命名带日期。历史快照功能虽然好用，但它通常只保留最近若干条，时间一长早期的就滚掉了。key 这类东西一旦丢了，重新申请是很烦的。

6.2 分发模板时把密钥留空

给团队发配置，正确姿势是导出模板、清空密钥字段、附一份填写说明。接收方导入后自己填 key，工具会把它存在本地的档案里，不会跟着模板走。这样即使模板文件被传到公共位置，泄露的也只是地址和模型名，不含凭据。

如果你的工具版本不支持模板导出，那就手工做：新建一份纯文本，只写字段名和示例值，别写真实 key。多花两分钟，省掉一次事故。

6.3 什么时候该回到脚本

CC Switch 覆盖不了两个场景：无图形界面的环境（比如远程会话、CI 机器）和需要和其他动作串联的流程（比如切完配置顺便拉一次代码、跑一次冒烟测试）。这两种情况用 PowerShell 函数更合适：

function Use-ProfileA { $cfg = "$env:USERPROFILE\.claude\settings.json" Copy-Item $cfg "$cfg.bak" -Force $json = Get-Content "$env:USERPROFILE\.ccswitch\profileA.json" -Raw Set-Content $cfg $json -Encoding utf8NoBOM Write-Host "已切换到 A 档案，请重开终端" -ForegroundColor Green }

图形工具负责日常手点，脚本负责自动化和兜底，两者不冲突。我现在的用法就是这样：桌面点得多的时候用 CC Switch，写批处理的时候用脚本。

7. 我这段时间踩过的几个具体坑

第一个坑：切换后忘了切回来，用高成本配置跑了一整晚的批量任务。教训是给不同成本的档案起明显不同的名字，并且在工具里把常用的那条设成"默认恢复项"，出问题能一键回去。

第二个坑：在settings.json里加了注释。JSON 不支持注释，加了一行// 临时之后整个文件解析失败，而助手的表现是安静地用回了内置默认值，看起来像是"配置被重置了"。这个坑花了我快一个小时，因为报错信息完全没有指向语法错误。

第三个坑：路径里有中文字符和空格。把工具装到了D:\我的软件\CC Switch\下面，某些版本的子进程调用会因为没做引号转义而失败。后来统一装到D:\Tools\ccswitch\这种纯英文短路径，问题消失。Windows 上这条经验几乎是通用的，凡是带子进程的工具，路径越干净越好。

第四个坑：杀软实时扫描导致切换瞬时锁文件。切换的瞬间工具要覆写settings.json，如果刚好赶上扫描器在读这个文件，写入会失败但界面提示成功。表现是"点了没反应"。解决办法是给配置目录加个排除项，或者切完顺手看一眼文件修改时间确认。

第五个坑：以为工具会自动同步多台机器。它不会。每台机器上的档案库是独立的，想让家里和公司两台机器配置一致，得自己解决同步——但千万别把带 key 的档案库丢进公共同步目录。我现在是用一个加密压缩包手动搬，虽然笨，但心里踏实。

最后一个体会：这类工具的价值不在于它省了你多少次点击，而在于它把"配置"这件事从散落在磁盘各处的隐式状态，变成了一个有名字、有快照、可回滚的显式对象。一旦配置变成显式对象，你就可以对它做版本管理、做评审、做交接。之前那种"配置在我脑子里"的状态，才是真正让人焦虑的根源。