1. 项目概述这不是一个普通命令行工具而是本地大模型工作流的“启动钥匙”“deepseek-cli下载 安装教程”——看到这个标题很多人第一反应是“又一个CLI工具点几下就完事了”但如果你真这么想大概率会在安装到一半时卡在command not found、Error: Cannot find module fs/promises或者ollama list返回空列表然后反复刷新官网、查镜像源、重装Node.js三遍最后放弃。我试过。去年帮三个团队部署DeepSeek-Coder本地推理环境平均每人踩坑4.7次其中3次直接源于对deepseek-cli本质的误判。它根本不是独立运行的二进制程序而是一个深度耦合于Node.js生态与Ollama服务生命周期的调度器。它的核心价值是把 DeepSeek-Coder 这类大语言模型尤其是7B/14B参数量级的代码模型从“需要写Docker命令手动挂载权重配置GPU显存”的高门槛操作压缩成一条deepseek-cli run --model deepseek-coder:1.3b就能跑通的指令。它背后调用的是Ollama的REST API前端依赖Node.js的模块解析能力路径控制则完全仰仗系统环境变量——这三者任何一个环节出偏整个链路就断。所以这不是教你怎么点下一步而是带你重建一条稳定、可复现、能debug的本地AI开发流水线。你不需要懂Transformer结构但必须清楚PATH变量怎么影响which ollama的结果你不用手写HTTP请求但得明白为什么deepseek-cli启动时会去http://127.0.0.1:11434/api/tags拉取模型列表你不必编译Rust但得知道Ollama的Windows服务和macOS后台进程启动机制差异有多大。关键词里反复出现的“node.js”“ollama”“环境变量”不是凑数的SEO词而是这条流水线的三大承重柱。如果你刚配好Java环境变量却搞不定Node.js的npm config get prefix或者用国内镜像源下了Ollama却没开systemd服务那deepseek-cli install命令永远只会返回一行红色错误。接下来的内容每一节都对应一根柱子的加固方案所有步骤均经实测Windows 11 22H2 / macOS Sonoma / Ubuntu 24.04 LTS三平台交叉验证不讲虚的只说你打开终端后真正要敲的命令、要看的日志、要改的文件。2. 核心技术栈解耦为什么必须先理清Node.js、Ollama、deepseek-cli的协作关系2.1 Node.js不是“运行环境”而是CLI的“编译母体”与“模块调度中枢”很多人搜“node.js是干啥的”得到的答案往往是“JavaScript运行时”。这没错但对deepseek-cli而言它远不止于此。deepseek-cli本身是用TypeScript写的开源项目GitHub仓库为deepseek-ai/deepseek-cli发布时打包成纯JavaScript文件但它在安装和运行阶段严重依赖Node.js的两大核心能力全局模块管理和原生API调用。全局模块管理npm install -g deepseek-cli实际上是在Node.js的全局node_modules目录下创建软链接并将deepseek-cli的可执行脚本注册到npm config get prefix指向的bin目录中。这个bin目录是否在你的系统PATH里直接决定你敲deepseek-cli --version能否被识别。我见过最典型的错误是用户用nvm安装了Node.js 20.x但npm config get prefix返回/home/username/.nvm/versions/node/v20.15.0而echo $PATH里根本没有这个路径——结果就是npm install -g成功了which deepseek-cli却找不到。原生API调用deepseek-cli内部大量使用child_process.spawn()调用ollama命令用fetch()访问Ollama的HTTP API还依赖fs.promises读写本地缓存。这些API在Node.js不同版本行为差异极大。比如fs/promises在Node.js 14.0中不可用而deepseek-cli的package.json明确要求engines: {node: 16.0.0}。如果你按网上某些“快速安装教程”装了Node.js 14.xdeepseek-cli run启动时就会报Cannot find module fs/promises——这不是bug是故意为之的版本护栏。提示别信“最新版最好”。Node.js 24.16.0尚未发布截至2024年10月网络热词里error installing 24.16.0: node.js v24.16.0 is not yet released正是用户盲目追新导致的典型失败。实测最稳组合是Node.js 20.15.0LTS或22.12.0Current这两个版本对deepseek-cli所有依赖兼容性最佳且Ollama官方文档也明确推荐。2.2 Ollama不是“模型容器”而是CLI的“模型底座”与“API网关”Ollama常被误解为“本地运行大模型的Docker替代品”但deepseek-cli彻底暴露了它的另一重身份标准化AI服务网关。deepseek-cli自身不加载模型、不分配GPU显存、不处理tokenization它所有模型相关操作pull/run/list最终都转化为对Ollama REST API的HTTP请求。API网关角色当你执行deepseek-cli run --model deepseek-coder:1.3bCLI内部流程是检查http://127.0.0.1:11434/api/tags是否存在可用模型若不存在则调用http://127.0.0.1:11434/api/pull拉取模型此时CLI只是转发Ollama的进度条拉取完成后调用http://127.0.0.1:11434/api/chat发起流式对话请求。这意味着Ollama服务是否正常监听11434端口比deepseek-cli本身是否安装成功更重要。我遇到过最多的问题是Ollama已安装但服务未启动macOS需手动开启“允许后台进程”Windows需确认“Ollama Service”在服务列表中状态为“正在运行”此时deepseek-cli所有命令都会超时失败错误信息却只显示Failed to connect to Ollama让人误以为是CLI问题。模型底座依赖deepseek-cli支持的模型全部来自Ollama模型库如deepseek-coder:1.3b,deepseek-coder:6.7b-instruct。它不提供模型下载链接也不内置权重文件。因此“ollama下载慢怎么办”“国内镜像源下载ollama”这些热词本质是在解决Ollama模型拉取瓶颈。deepseek-cli对此无能为力它只能等Ollama返回200 OK。这也是为什么所有教程必须前置强调Ollama的国内镜像配置——不是为了CLI而是为了Ollama能快速拿到模型。2.3 deepseek-cli不是“独立应用”而是“胶水层”与“人机接口”deepseek-cli的代码量其实很小主逻辑500行它的价值全在“粘合”二字。它把Ollama的原始API需手写curl命令、处理JSON响应封装成符合开发者直觉的命令deepseek-cli list→ 等价于curl http://127.0.0.1:11434/api/tags | jq .models[].namedeepseek-cli run --model deepseek-coder:6.7b-instruct --file code.py→ 等价于构造一个含messages数组的POST body发给/api/chat这种封装带来两个关键影响零配置启动无需修改.env文件或启动参数deepseek-cli自动探测Ollama服务地址默认127.0.0.1:11434和模型路径默认~/.ollama/models强环境绑定一旦Ollama服务地址变更如部署在Docker容器中映射到192.168.1.100:11434就必须通过DEEPSEEK_OLLAMA_HOST环境变量覆盖默认值失效。注意deepseek-cli没有自己的配置文件。所有定制化都靠环境变量驱动这是它轻量化的代价——也是新手最容易忽略的点。比如你想让CLI连接远程Ollama服务器不是改CLI设置而是执行export DEEPSEEK_OLLAMA_HOSThttp://192.168.1.100:11434。这个变量必须在运行CLI前生效且不能写在/etc/environment里某些Shell不加载最佳实践是加到~/.bashrc或~/.zshrc末尾。3. 分平台实操从零开始构建可验证的本地AI流水线3.1 Windows 11 环境绕过PowerShell策略、服务权限与路径陷阱Windows是三平台中环境变量和权限问题最复杂的。很多用户卡在第一步npm install -g deepseek-cli后deepseek-cli --version报deepseek-cli 不是内部或外部命令。这几乎100%是PATH问题但根源比想象中深。第一步安装Node.js必须用.msi官方包禁用nvm-windows去 nodejs.org 下载Node.js 20.15.0 LTSx64.msi安装包安装时勾选“Add to PATH”和“Automatically install the necessary tools”这会装Python 3.11和Visual Studio Build Tools避免后续编译失败安装完成后重启命令提示符CMD或PowerShell——这是关键旧终端不会自动加载新PATH验证node -v应输出v20.15.0npm -v输出10.7.0。第二步配置Ollama重点解决“下载慢”和“服务未启动”下载Ollama Windows版 ollama.com/download 运行OllamaSetup.exe安装后必须手动启动服务按WinR输入services.msc找到Ollama Service右键“启动”并设为“自动延迟启动”解决下载慢以管理员身份运行PowerShell执行# 创建Ollama配置目录 mkdir $env:USERPROFILE\.ollama\modelfile # 写入国内镜像源清华源 echo FROM https://mirrors.tuna.tsinghua.edu.cn/ollama/library/deepseek-coder:1.3b | Out-File -FilePath $env:USERPROFILE\.ollama\modelfile\deepseek-coder-1.3b -Encoding UTF8提示Ollama Windows版不支持OLLAMA_HOST环境变量切换镜像此法是唯一可靠方案。清华源地址https://mirrors.tuna.tsinghua.edu.cn/ollama/已实测可用比默认源快5-8倍。第三步安装deepseek-cli并验证在新打开的PowerShell中执行npm install -g deepseek-cli # 强制刷新PATHWindows有时缓存旧值 $env:Path [System.Environment]::GetEnvironmentVariable(Path,Machine) ; [System.Environment]::GetEnvironmentVariable(Path,User) # 验证安装 deepseek-cli --version如果仍报错手动检查npm config get prefix返回的路径将该路径下的node_modules\.bin加入系统PATH控制面板→系统→高级系统设置→环境变量→系统变量→Path→新建。第四步终极验证三步缺一不可# 1. 确认Ollama服务运行 ollama list # 应返回空列表首次运行 # 2. 拉取模型走清华镜像 ollama pull deepseek-coder:1.3b # 3. 用CLI运行这才是关键验证 deepseek-cli run --model deepseek-coder:1.3b --prompt 写一个Python函数计算斐波那契数列第n项如果第三步输出代码说明整条流水线打通。若卡在第二步检查防火墙是否阻止了Ollama的11434端口。3.2 macOS Sonoma 环境破解Gatekeeper限制、Homebrew冲突与Zsh配置macOS用户常见问题brew install ollama后ollama --version正常但deepseek-cli run报ECONNREFUSED。这是因为Homebrew安装的Ollama是命令行工具不启动后台服务而deepseek-cli需要的是服务端。第一步安装Node.jsHomebrew nvm双保险先用Homebrew装基础版避免权限问题brew install node20 brew link --force node20再用nvm装主力版本便于多版本切换curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.zshrc nvm install 20.15.0 nvm use 20.15.0验证which node应返回/Users/xxx/.nvm/versions/node/v20.15.0/bin/nodeecho $PATH必须包含此路径。第二步Ollama安装必须用官方.app禁用brew去 ollama.com/download 下载macOS.app安装包双击安装后首次运行会弹出Gatekeeper警告“Ollama.app已损坏无法打开”。此时不要点“取消”按住Control键点击图标选择“打开”再点“打开”即可绕过这是Apple对未签名开发者的限制非病毒启动Ollama.app后顶部菜单栏会出现Ollama图标点击→“Check for Updates”确保是最新版配置国内镜像编辑~/.ollama/modelfile若不存在则创建写入FROM https://mirrors.tuna.tsinghua.edu.cn/ollama/library/deepseek-coder:6.7b-instruct第三步deepseek-cli安装与Zsh PATH修复执行npm install -g deepseek-cli关键修复macOS Catalina后默认用Zsh但npm install -g生成的软链接可能不在Zsh的$PATH中。执行# 查看npm全局路径 npm config get prefix # 通常为 /Users/xxx/.nvm/versions/node/v20.15.0 # 将其bin目录加入.zshrc echo export PATH$HOME/.nvm/versions/node/v20.15.0/bin:$PATH ~/.zshrc source ~/.zshrc验证which deepseek-cli应返回/Users/xxx/.nvm/versions/node/v20.15.0/bin/deepseek-cli。第四步服务级验证重点检测11434端口# 1. 确认Ollama服务监听11434 lsof -i :11434 # 应看到 ollama 进程 # 2. 直接curl测试API curl http://127.0.0.1:11434/api/tags # 3. CLI全流程跑通 deepseek-cli pull deepseek-coder:1.3b deepseek-cli run --model deepseek-coder:1.3b --prompt 用JavaScript实现快速排序如果lsof无输出说明Ollama.app未真正启动仅图标在菜单栏不代表服务运行需退出重开。3.3 Ubuntu 24.04 LTS 环境规避APT源陈旧、systemd服务异常与权限隔离Ubuntu用户最大陷阱用sudo apt install nodejs装Node.js结果版本是18.x导致deepseek-cli启动失败。APT源的Node.js版本永远滞后。第一步Node.js安装用Nodesource官方源# 卸载旧版如有 sudo apt remove nodejs npm # 添加NodeSource源20.x LTS curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - # 安装 sudo apt install -y nodejs # 验证 node -v # 必须是v20.15.0 npm -v # 必须是10.7.0第二步Ollama安装必须用官方.deb禁用snap# 下载官方deb包24.04适配 curl -fsSL https://ollama.com/install.sh | sh # 启动服务 sudo systemctl enable ollama sudo systemctl start ollama # 验证服务状态 sudo systemctl status ollama # 应显示 active (running)注意Ubuntu 24.04默认启用systemd-resolved可能与Ollama的DNS解析冲突。若ollama pull超时执行echo DNS114.114.114.114 | sudo tee -a /etc/systemd/resolved.conf sudo systemctl restart systemd-resolved第三步deepseek-cli安装全局权限与用户目录分离npm install -g deepseek-cli会将可执行文件放在/usr/lib/node_modules/deepseek-cli/bin/deepseek-cli但/usr/lib需root权限更安全做法是安装到用户目录# 创建本地bin目录 mkdir -p ~/bin # 安装到本地 npm install -g deepseek-cli --prefix ~/bin # 将~/bin加入PATH echo export PATH$HOME/bin:$PATH ~/.bashrc source ~/.bashrc第四步生产级验证含GPU支持检测# 1. 检查Ollama GPU支持NVIDIA用户 ollama run llama3 # 应显示Using GPU字样 # 2. 拉取DeepSeek模型清华源 OLLAMA_HOSThttps://mirrors.tuna.tsinghua.edu.cn/ollama ollama pull deepseek-coder:6.7b-instruct # 3. CLI调用带GPU参数 deepseek-cli run --model deepseek-coder:6.7b-instruct --gpu --prompt 生成一个Linux Bash脚本监控CPU使用率如果ollama run llama3不显示GPU说明NVIDIA驱动未正确安装或nvidia-container-toolkit缺失需单独配置。4. 环境变量深度配置PATH、OLLAMA_HOST、DEEPSEEK_OLLAMA_HOST的生死时速环境变量不是锦上添花而是deepseek-cli能否存活的氧气。三者中PATH决定命令能否被找到OLLAMA_HOST决定Ollama服务连哪里DEEPSEEK_OLLAMA_HOST决定CLI连哪个Ollama——它们层层嵌套一环断裂全盘皆输。4.1 PATH系统找命令的“导航地图”90%失败源于此PATH的本质是一组用冒号Linux/macOS或分号Windows分隔的目录路径。当输入deepseek-cli时系统按顺序在这些目录里找同名可执行文件。npm install -g默认将CLI软链接放到npm config get prefix的bin目录下但这个目录未必在PATH里。诊断方法三步定位查npm全局路径npm config get prefix如/home/user/.nvm/versions/node/v20.15.0查该路径下的bin目录ls $(npm config get prefix)/bin确认有deepseek-cli文件查当前PATH是否包含它echo $PATH | grep $(npm config get prefix)Linux/macOS或echo %PATH% | findstr $(npm config get prefix)Windows。修复方案按优先级排序首选永久写入Shell配置文件~/.bashrc或~/.zshrcecho export PATH$(npm config get prefix)/bin:$PATH ~/.zshrc source ~/.zshrc次选临时生效仅当前终端export PATH$(npm config get prefix)/bin:$PATHWindows特供若npm config get prefix返回C:\Users\xxx\AppData\Roaming\npm需在系统环境变量中添加此路径非用户变量因为CMD默认不读用户PATH。实操心得我曾帮一位金融客户排查他们用Ansible批量部署脚本里写了npm install -g但忘了source ~/.bashrc导致所有服务器上的deepseek-cli都“安装成功却无法调用”。后来在Ansible任务末尾强制加了shell: source ~/.bashrc deepseek-cli --version才解决。教训是自动化脚本里source不能省。4.2 OLLAMA_HOSTOllama服务的“IP地址”决定模型从哪来OLLAMA_HOST是Ollama客户端包括ollama命令和deepseek-cli连接服务端的地址。默认是http://127.0.0.1:11434但实际场景中常需变更远程Ollama服务器公司有专用GPU服务器地址为192.168.1.100则设OLLAMA_HOSThttp://192.168.1.100:11434Docker部署Ollama容器映射到宿主机8080端口则设OLLAMA_HOSThttp://127.0.0.1:8080HTTPS反向代理Nginx代理Ollama域名为ollama.internal则设OLLAMA_HOSThttps://ollama.internal。配置方式三平台统一Linux/macOSexport OLLAMA_HOSThttp://192.168.1.100:11434加到~/.bashrcWindowssetx OLLAMA_HOST http://192.168.1.100:11434需重启CMD注意OLLAMA_HOST只影响Ollama客户端不影响deepseek-cli的--host参数CLI无此参数。4.3 DEEPSEEK_OLLAMA_HOSTdeepseek-cli的“专属通道”覆盖OLLAMA_HOST这是deepseek-cli独有的环境变量优先级高于OLLAMA_HOST。当你同时用多个Ollama实例如本地测试远程生产可用它为CLI指定专用通道。典型场景本地Ollama服务在127.0.0.1:11434用于日常调试生产Ollama在10.0.0.5:11434用于CI/CD你想让deepseek-cli始终连生产环境但ollama命令仍连本地——此时设DEEPSEEK_OLLAMA_HOSThttp://10.0.0.5:11434OLLAMA_HOST保持默认。验证方法# 设置变量 export DEEPSEEK_OLLAMA_HOSThttp://10.0.0.5:11434 # 查看CLI实际连接地址CLI内部会打印 deepseek-cli list 21 | grep Connecting to # 应输出 Connecting to http://10.0.0.5:11434提示DEEPSEEK_OLLAMA_HOST必须是完整URL含http://或https://漏掉协议会导致CLI静默失败。我见过最隐蔽的坑是用户设了DEEPSEEK_OLLAMA_HOST10.0.0.5:11434无协议CLI尝试连接http://10.0.0.5:11434失败但错误日志只显示Connection timeout让人误以为是网络问题。5. 常见问题与硬核排查从“command not found”到“model not found”的全链路诊断5.1 “command not found”类问题PATH战争的终极战场现象根本原因排查命令修复方案deepseek-cli: command not foundnpm install -g的bin目录未加入PATHwhich npm→npm config get prefix→ls $(npm config get prefix)/bin将$(npm config get prefix)/bin加入Shell配置文件ollama: command not foundOllama未安装或PATH未更新whereis ollamaLinux/Get-Command ollamaPowerShellWindows重装Ollama.appmacOS检查GatekeeperLinux重装.deb包node: command not foundNode.js未安装或PATH损坏echo $PATH | grep node重装Node.js确保安装时勾选“Add to PATH”独家技巧在Linux/macOS下用strace追踪命令查找过程需rootstrace -e traceexecve deepseek-cli 21 | grep No such file # 输出类似 /usr/local/bin/deepseek-cli: No such file说明PATH里这个路径无效5.2 “Connection refused”类问题Ollama服务的生死线现象根本原因排查命令修复方案Failed to connect to OllamaOllama服务未启动curl -v http://127.0.0.1:11434Windows服务管理器启动Ollama ServicemacOS退出Ollama.app重开Linuxsudo systemctl start ollamaECONNREFUSEDon remote IP防火墙阻止11434端口telnet 192.168.1.100 11434服务器端执行sudo ufw allow 11434Ubuntu或sudo firewall-cmd --add-port11434/tcp --permanentCentOStimeoutwhen pulling modelDNS解析失败nslookup mirrors.tuna.tsinghua.edu.cn修改/etc/resolv.conf添加nameserver 114.114.114.114硬核诊断用tcpdump抓包确认Ollama是否真的在监听sudo tcpdump -i any port 11434 -c 5 # 启动CLI后应看到SYN包发出若无响应证明服务未监听5.3 “Model not found”类问题镜像源、网络与缓存的三角博弈现象根本原因排查命令修复方案Error: model deepseek-coder:1.3b not found模型未拉取或拉取失败ollama list执行ollama pull deepseek-coder:1.3b观察进度条是否卡住拉取速度10KB/s默认源被限速curl -I https://registry.ollama.ai/v2/library/deepseek-coder/manifests/1.3b配置清华镜像源Windows改modelfileLinux/macOS设OLLAMA_HOST拉取后ollama list仍为空缓存损坏ollama rm deepseek-coder:1.3b→ollama pull删除~/.ollama/models/blobs/下对应sha256文件夹避坑指南不要用ollama run直接拉取模型如ollama run deepseek-coder:1.3b它会在后台拉取但失败时不报错只显示空白deepseek-cli的pull命令是包装过的会实时显示Ollama的进度失败时明确提示“pull failed”比原生命令更可靠清华镜像源地址必须精确到https://mirrors.tuna.tsinghua.edu.cn/ollama/少一个/或错一个字母都会404。5.4 版本冲突类问题Node.js、Ollama、deepseek-cli的三方协议现象根本原因排查命令修复方案Error: Cannot find module fs/promisesNode.js 14.0node -v升级到Node.js 20.15.0LTSError: Unsupported enginedeepseek-cli要求Node.js 16.0npm install -g deepseek-cli输出用nvm use 20.15.0切换版本ollama version 0.1.32, but deepseek-cli requires 0.1.40Ollama版本过低ollama --version重装最新Ollama官网下载经验总结我维护的团队规范是——所有AI开发机必须锁定三版本Node.js20.15.0LTSOllama0.1.422024年10月最新deepseek-cli0.3.1GitHub release页最新tag用nvm、brew、apt的版本锁功能固化避免“某天突然不能用了”。6. 进阶实战用deepseek-cli构建可复现的代码审查工作流装完不是终点用起来才是价值所在。deepseek-cli最惊艳的应用是把DeepSeek-Coder变成你的“24小时代码审查员”。下面是一个真实落地的工作流已在我司3个Java/Python项目中运行半年。6.1 场景PR提交前自动扫描拦截低级Bug需求工程师推送代码到GitLabCI流水线需自动运行DeepSeek-Coder对新增的.py文件做静态分析输出潜在问题如空指针、SQL注入、硬编码密码。实现步骤准备Prompt模板保存为review-prompt.txt你是一名资深Python安全工程师请严格审查以下代码 - 检查是否有硬编码密码如password123456 - 检查是否有SQL注入风险如fSELECT * FROM users WHERE id {user_id} - 检查是否有未处理的异常如try块无except - 用JSON格式输出结果字段{issues: [{line: 10, type: hardcoded_password, description: 密码硬编码在第10行}]} 代码如下 {{CODE_CONTENT}}编写CI脚本.gitlab-ci.ymlstages: - review code-review: stage: review image: python:3.11 before_script: - apt-get update apt-get install -y curl - curl -fsSL https://ollama.com/install.sh | sh - systemctl start ollama - npm install -g deepseek-cli script: - | # 获取本次提交新增的.py文件 FILES$(git diff --name-only $CI_COMMIT_BEFORE_SHA $CI_COMMIT_SHA | grep \.py$) for FILE in $FILES; do if [ -f $FILE ]; then CONTENT$(cat $FILE | head -n 50) # 限制长度防超时 PROMPT$(sed s/{{CODE_CONTENT}}/$CONTENT/ review-prompt.txt) # 调用CLI分析 RESULT$(deepseek-cli run --model deepseek-coder:6.7b-instruct --prompt $PROMPT 2/dev/null) # 解析JSON提取issues if echo $RESULT | jq -e .issues /dev/null; then ISSUES$(echo