企业官网建设流程全解析

最近好几个做开发的朋友都在问同一个问题：在 Ubuntu 上装 Claude Code，然后接 DeepSeek API，到底怎么弄才能一次跑通？说实话，这个组合的官方文档东一块西一块，网上教程又大多是 Windows 和 macOS 的，到了 Ubuntu 就各种报错——Node 版本不对、npm 权限不足、“request to https://api.deepseek.com failed”，心态很容易崩。这篇文章我直接用自己重装了三次才跑通的完整流程，把 Ubuntu 下安装 Claude Code 并接入 DeepSeek API 的步骤、配置原理和排查思路全部讲清楚。内容适合要在 Linux 环境里用 AI 编程助手的开发者，也适合刚从 Windows 转过来、第一次在 Ubuntu 上装开发工具的新手。跟着这套流程走，我实测下来基本一把过，剩下的事就是怎么用好它。

1. 为什么选这个组合：Ubuntu + Claude Code + DeepSeek 的定位分析

1.1 先说结论：这个组合解决什么问题

Claude Code 是 Anthropic 推出的终端 AI 编程助手，直接跑在命令行里，能读你项目的文件、帮你改代码、执行命令、提交 Git。它最大的特点是和终端工作流浑然一体：你在哪个目录启动，它就能基于这个目录的上下文干活，不像有些 AI 工具要手动把代码复制到网页里。

但 Claude Code 原生是面向 Anthropic 官方 API 设计的，官方接口按量付费，而且对国内开发者来说还有支付门槛。DeepSeek API 的出现把这个问题解决了——它提供了兼容接口，价格便宜得多，国内直接就能用，充个几十块钱能用很久。于是“Claude Code + DeepSeek API”就成了很多人的低成本替代方案：用的还是 Claude Code 的交互体验，底下的模型换成 DeepSeek，成本一下子从天上掉到地上。

Ubuntu 作为开发环境则有两个天然优势：一是终端体验完整，Claude Code 这种纯 CLI 工具在 Linux 下运行最稳；二是资源占用低，哪怕你是在虚拟机上装 Ubuntu，跑起来也比 Windows 下顺畅。我自己的主力机就是 Ubuntu 22.04 LTS，Claude Code 基本常驻终端。如果你只是偶尔用 AI 写一小段代码，那 Web 版就够了；但如果你希望 AI 能直接读你的项目、跑测试、改文件，那终端方案的价值就出来了。

1.2 和 Codex、Web 版、Ollama 的对比

很多人在选型时纠结这三个：Claude Code、OpenAI Codex、Web 聊天版，还有本地模型 Ollama。我整理了一个选型表格，方便你对号入座：

选型逻辑其实很清楚：要的是“AI 能进到项目里干活”，而不只是“AI 能聊天”。Claude Code 能直接帮你跑测试、改文件、看报错，这是 Web 版代替不了的。Codex 体验也不错，但在国内的使用门槛（支付、网络）比 DeepSeek 高。Ollama 适合对隐私有要求的场景，但本地跑大模型需要不错的显卡，笔记本上效果一般。所以如果你想要一个”开箱即用、成本极低、终端优先“的方案，Ubuntu + Claude Code + DeepSeek 就是目前最务实的组合。

1.3 装之前先把 Ubuntu 基础环境弄顺

如果你的 Ubuntu 刚装好，建议先花十分钟把这几件事处理掉，不然后面每一步都可能被无关问题卡住：

• 网络：确认能正常访问目标服务和 npm 源。在国内环境，把 apt 源换成国内镜像、npm 源换成国内镜像，能省大量时间。
• SSH（可选）：如果你是在虚拟机或远程服务器上操作，先确认能正常连上，后面排查报错会轻松很多。
• 中文输入法：很多从 Windows 转过来的用户第一件事就是装搜狗输入法。Ubuntu 上输入法框架建议用 fcitx5，装搜狗前先确认框架一致，否则装完无法切换，这个坑我踩过一次。
• sudo 权限：记好你的用户密码。如果需要切换超级管理员，终端执行 sudo -i 即可，输入的密码就是你当前用户的密码；如果没设置过 root 密码，可以用 sudo passwd root 设置。

这些都是基础但实用的内容。我见过太多人卡在“claude 命令找不到”这种问题上，结果查了半天发现是 Node 压根没装好。基础环境理顺了，后面主流程就是一路畅通。

2. Node.js 与 Claude Code 安装：版本坑和权限问题是重灾区

2.1 别用 apt 装 Node，用 nvm

Ubuntu 的软件源里虽然有 nodejs，但版本往往偏旧，而且系统自带的版本和 npm 的全局安装联动经常出问题。Claude Code 对 Node 版本有要求，太旧的版本装完启动就报错。我强烈建议用 nvm 管理 Node 版本。

安装 nvm：

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

装完重新打开终端，或者执行 source ~/.bashrc 让它生效，然后执行：

nvm install 20 nvm alias default 20

我选用 Node 20 LTS，实测很稳。Claude Code 官方要求 Node 18+，但 Node 20 在性能和兼容性上都更好。Node 22 也可以，但有些旧 npm 包可能还没跟上，没必要冒险。

这里解释一下为什么不要用 apt 直接装：apt 装出来的 nodejs 在 /usr/bin 下，全局 npm 包要写 /usr/lib/node_modules，权限问题一堆，动不动就 EACCES。nvm 把 Node 装在用户目录下，不需要 root 权限，全局包也归自己管，后面装 Claude Code 会省心很多。

2.2 安装 Claude Code 的两种方式和推荐选择

官方给了两种安装方式，我在实际测试中都跑过：

方式一，curl 脚本安装：

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

方式二，npm 全局安装：

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

两者本质一样，官方脚本底层还是调 npm，但多了自动检测环境、配置 PATH 的步骤。问题在于：如果你用 nvm 管理 Node，官方脚本有时候会检测不到 nvm 的环境变量，导致装完以后 claude 命令找不到。所以我的建议是直接用 npm 方式装，简单直接，状态完全可控。

国内网络环境下载 npm 包可能比较慢，先把 npm 源切到国内镜像：

npm config set registry https://registry.npmmirror.com

切完再装，速度会快很多。网上很多帖子提到的“claude code powershell 安装报错”，那是 Windows 上的问题，Ubuntu 这边用 bash 流程不会碰到那个坑，放心。

2.3 验证安装和更新

装完以后，先确认版本：

claude --version

如果能正常输出版本号，说明 Claude Code 本体已经 OK。如果提示 command not found，大概率是 nvm 的 PATH 没生效。重新打开终端，或者执行 source ~/.bashrc 再试。

日常更新就用 npm 全局包的标准方式：

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

2.4 顺手解决 npm 全局目录权限问题

如果你不是用 nvm，而是用系统自带的 Node，装的时候会看到 EACCES 权限错误。这里不建议用 sudo npm install -g，因为 sudo 会把全局包装到 root 的目录，之后普通用户运行 claude 又找不到。正确做法是改 npm 的全局目录：

mkdir -p ~/.npm-global npm config set prefix '~/.npm-global' echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc

然后再执行 npm install -g @anthropic-ai/claude-code 就不会有权限问题了。这个问题我在帮朋友排查时遇到过好几次，基本都是因为图省事用了 sudo，结果后面引出更多幺蛾子。

3. DeepSeek API 接入：环境变量配置的原理与实操

3.1 先理解 Claude Code 的 API 接入机制

Claude Code 本身是按 Anthropic API 协议设计的客户端。所谓“接入 DeepSeek”，就是告诉它：你的 API 地址和鉴权信息都换掉，你用的是另一个兼容 Anthropic 协议的后端。

Claude Code 启动时会读取几个关键环境变量：

• ANTHROPIC_BASE_URL：API 请求的基础地址，默认是 Anthropic 官方地址
• ANTHROPIC_AUTH_TOKEN：认证用的 Token，代替 API Key
• ANTHROPIC_MODEL：使用的模型名称
• ANTHROPIC_API_KEY：部分版本也支持这个变量

DeepSeek 提供的是 OpenAI 兼容接口，社区通常通过一个 Anthropic 兼容转发层来对接，主流做法是把 ANTHROPIC_BASE_URL 指向 DeepSeek 的 Anthropic 兼容端点。这个端点在不同接入方式下略有差异，最常见的是：

https://api.deepseek.com/anthropic

如果你用的版本请求这个地址一直报 404，可以试试本地协议转换方案，但大多数情况下上面这个端点就够了。这不是什么黑科技，就是把 Claude Code 发出的 Anthropic 协议请求，转换成 DeepSeek 能理解的请求格式，原理上就是一个协议适配层。

3.2 申请 DeepSeek API Key

打开 DeepSeek 开放平台，注册账号、充值，然后在“API Keys”页面创建新的 Key。注意几个细节：

• Key 只显示一次，创建完立刻复制保存，丢了只能重新生成
• 建议给 Key 起一个能认出来的名字，比如 claude-code-ubuntu
• 充值按需来，先充 10 块 20 块试试，DeepSeek 的价格很便宜，够用很久

3.3 配置三个关键环境变量

打开你的 shell 配置文件。默认是 ~/.bashrc，如果你用的是 zsh，就是 ~/.zshrc。在文件末尾加上：

export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic" export ANTHROPIC_AUTH_TOKEN="sk-你的DeepSeek密钥" export ANTHROPIC_MODEL="deepseek-chat"

这里有个很重要的细节：ANTHROPIC_MODEL 这个名字看起来是给 Anthropic 模型用的，但在 DeepSeek 接入场景里，它用来指定 DeepSeek 的模型名。deepseek-chat 对应 DeepSeek-V3 系列，deepseek-reasoner 对应带推理能力的模型。日常写代码用 deepseek-chat 就够，速度和成本都更友好。

保存后执行：

source ~/.bashrc

然后验证环境变量是否生效：

echo $ANTHROPIC_BASE_URL echo $ANTHROPIC_AUTH_TOKEN

看到输出不是空的就是生效了。

3.4 验证配置是否生效

直接在项目目录里启动：

claude

如果配置没问题，它会跳过官方登录流程，直接进入对话界面。随便问一句“你好，请用一句话说明你是什么模型”，如果它回答自己是 DeepSeek，说明整条链路已经通了。

这里有个容易误解的点：Claude Code 刚启动时如果要求你登录 Anthropic 账号，那说明环境变量没被读到，或者是新开的终端没有 source。排查顺序：先 echo 两个变量，再看有没有写错文件，最后确认没有在别的配置文件里重复覆盖。

3.5 为什么我不建议只改 settings.json

网上有些教程会让你改 ~/.claude/settings.json，在 env 字段里写这些变量。这样也能生效，但有个问题：settings.json 是 Claude Code 内部的用户配置文件，不同版本的配置结构可能变化，升级后字段不兼容就会静默失效。环境变量是系统层面的标准机制，任何版本都认，而且你用 bash、zsh、脚本调用都一致。所以我建议配置尽量走环境变量，settings.json 留着做权限、MCP 这类 Claude Code 自己的功能配置。

4. 高频报错排查：从请求失败到限流警告的完整链路

这一章是避坑重点。我按报错出现的频率排序，把我重装三次和帮朋友排查时遇到的坑全部列出来。

4.1 “request to https://api.deepseek.com failed”的常见原因

这是热搜里出现频率最高的报错，完整信息一般长这样：

API request to https://api.deepseek.com/anthropic/messages failed

遇到这类网络请求失败，核心排查思路按顺序来：

第一，确认 Endpoint 地址对不对。如果 ANTHROPIC_BASE_URL 少写了 /anthropic 后缀，Claude Code 会往错误的路径发请求，DeepSeek 侧不处理 Anthropic 协议，直接返回错误。用 curl 手动测一下：

curl -v https://api.deepseek.com/anthropic

能看到 HTTP 响应而不是连接失败，说明网络通，问题在协议层。

第二，确认网络本身能通。Ubuntu 上如果设置了 HTTP_PROXY、HTTPS_PROXY 这类系统代理环境变量，Node 的请求会走代理，代理配置不对或者代理服务不可用，报错也是 network failed。先执行 curl -I https://www.baidu.com 确认基础网络通，再执行 curl -I https://api.deepseek.com 确认目标域名通。

第三，确认 DeepSeek 服务端状态。偶尔 DeepSeek API 会有服务波动，这个你自己控制不了，等一会儿重试。判断方法很简单：浏览器直接打开 DeepSeek 开放平台，如果网页能开但 API 请求失败，大概率是路径或协议有问题；网页也打不开，那就是网络或服务本身的问题。

4.2 401 认证失败，先别急着怀疑 Key

报错里出现 AuthenticationError 或者 HTTP 401，大部分时候不是 Key 本身坏了，而是环境变量没生效。常见场景：

• 你在一个终端里 export 了变量，然后新开了一个终端窗口，新窗口没 source，变量没了
• Key 复制的时候前面带了空格，或者被折叠换行
• 环境变量名拼写错了，比如写成 ANTHROPIC_AUTH_TOKEM 这种笔误

排查方法：

echo $ANTHROPIC_AUTH_TOKEN | wc -c

看输出是不是和你 Key 的长度匹配。DeepSeek Key 一般是 sk- 开头加一串字符，如果长度对不上，重新写一遍。然后确认当前 shell：

grep -n "ANTHROPIC" ~/.bashrc

确保 export 语句真的在配置文件里。

4.3 配额、限流与 “weekly limit” 提示

热搜里有一条很典型的提示：your limits are temporarily boosted. your weekly claude code limit is 50%。

这个信息很有意思。它的意思是：Claude Code 客户端内置了配额检测，正常情况下你用官方账号登录，客户端会统计每周的使用量。但当你用 DeepSeek 这类第三方 API 时，Claude Code 还是会尝试请求官方的配额服务，于是显示出这条提示。

遇到这个提示，不用慌，它不影响实际使用。你的请求已经发给 DeepSeek 了，配额统计是客户端层面的逻辑。如果它卡住导致无法进入对话，可以检查是不是有别的配置让 Claude Code 走了官方通道。真正要关注的限流是 DeepSeek 侧返回的 HTTP 429 Too Many Requests，说明你的并发或频率超过了 DeepSeek 的限制，降低请求频率、换个时间段再试就好。

4.4 命令找不到、启动黑屏这类基础问题

装了 claude 却说 command not found，原因基本是 PATH 没配置好。nvm 安装完 Node 后，npm 全局包的 bin 目录通常在 ~/.nvm/versions/node/v20.x.x/bin，如果这个目录不在 PATH 里，全局命令就找不到。重新打开终端一般能解决；不行就手动在 ~/.bashrc 里确认 nvm 的初始化代码是否存在。

如果启动 claude 以后界面空白、或者按回车没反应，多数是终端兼容性问题。Claude Code 对终端要求比较高，太老的终端或 tmux 版本可能有渲染问题。建议优先在系统自带终端或 VS Code 集成终端里跑，字体用等宽字体，避免用残缺的中文字体渲染导致界面错乱。

4.5 通用排查思路

最后给一套通用的排查框架，遇到任何报错都能用：

第一步，看完整报错，不要只看第一行。很多报错的关键信息在最后，或者中间的 cause 字段。

第二步，分清错误层。网络层错误一般带 ECONNREFUSED、ENOTFOUND、ETIMEDOUT；协议层错误一般带 HTTP 状态码 400/401/404/429；应用层错误一般是 JSON 解析、模型返回格式问题。不同层级的排查方向完全不同。

第三步，把请求详细日志打出来。Claude Code 支持 --debug 或 --verbose 参数（不同版本有差异），开启后能看到完整的请求日志，包括打到哪个 URL、带了什么 header。这一步能解决 80% 的配置问题。

第四步，看日志文件。Claude Code 会在 ~/.claude 目录下写日志，路径一般是 ~/.claude/launch.log 或者 ~/.claude/logs/ 下面，报错时先翻日志，比瞎猜高效得多。

5. 日常使用优化：VS Code 集成与成本控制

5.1 VS Code 里跑 Claude Code

Claude Code 的体验在纯命令行里已经很完整了，但配合 VS Code 会更顺手。官方有 Claude Code 的 VS Code 扩展，也可以在 VS Code 的集成终端里直接敲 claude，两边切换零成本。

我自己习惯把 Claude Code 放在 VS Code 的终端里用：左边看代码，右边跑 claude，让它改文件后直接 git diff 看变更。它在终端里能自动感知当前目录的 Git 状态，改完代码还能顺手帮你生成 commit message。如果你的项目本身在 VS Code 里管理，这种方式比单独开一个终端窗口更自然。

5.2 模型选择：deepseek-chat 还是 deepseek-reasoner

在 DeepSeek API 里，deepseek-chat 和 deepseek-reasoner 对应不同的模型能力。简单说：

• deepseek-chat：日常代码生成、重构、问答，速度更快，价格更低
• deepseek-reasoner：需要深度推理的任务，比如复杂 bug 分析、架构设计，会多一层思考过程，速度慢一些，价格更高

Claude Code 接入 DeepSeek 后，ANTHROPIC_MODEL 决定默认用的模型。我的建议是日常默认 deepseek-chat，遇到它搞不定的复杂问题，再临时切换。切换方式不用改环境变量，可以在 Claude Code 对话里用 /model 命令（如果版本支持），或者启动时带参数覆盖。具体命令以你装的版本为准，输入 /help 能看到当前版本支持的命令列表。

5.3 权限、上下文与成本

Claude Code 最大的特点是它能直接执行命令、改文件，这既是效率也是风险。第一次启动时它会扫描目录，并询问是否允许执行 shell 命令、修改文件等操作。建议在项目里配置权限白名单，把 AI 能执行的操作限制在当前项目目录内，别给它整个系统的访问权。

成本方面，重点看上下文。Claude Code 每次对话都会把项目文件作为上下文传过去，token 消耗比单纯聊天快得多。几个控制成本的方法：

• 项目文件太多时，用 .claudeignore 忽略不需要的文件，类似 .gitignore
• 单次任务尽量聚焦，不要在一个会话里堆积太多无关需求
• 发现它读入的文件太多，及时用 /clear 开新会话

DeepSeek 的定价很低，正常使用一个月一般也就几块钱到几十块钱，但养成这些习惯不仅能省钱，还能让 AI 的注意力更集中，回答质量也更高。

如果你以后想在 Claude Code 里切换多个供应商（比如官方 API、DeepSeek、本地 Ollama），社区里也有配置管理工具可以做多套环境变量的切换，本质上就是帮你切换这几组配置。如果只是接 DeepSeek 一个供应商，手写环境变量就足够了，不必引入额外工具。

最后再分享一点个人体会。这次从零开始装 Claude Code，我踩得最深的坑不是安装本身，而是“以为装好就完事了”。Claude Code 这种工具，配好只是第一步，真正让它产生价值的是后面的使用习惯：给它合适的权限、控制上下文、选对模型。在 Ubuntu 上的这套流程我已经完整跑通三遍，第一次花了半小时，后面熟了基本两分钟搞定。如果你装的过程中遇到我上面没提到的报错，记住一个原则：优先看日志，找到真正报错的那一行，再决定下一步操作，别被长长的错误堆栈吓到。