哈喽各位，今天我给大家整理了一篇保姆级部署指南，专门帮刚接触Ubuntu的小白和有一定基础却踩过坑的开发者解决在Ubuntu系统上搭建Claude CodeUI的各类难题，大家跟着这份教程一步步操作就能顺利完成部署，全程没有复杂步骤也没有多余内容，所有命令和注意点都标得明明白白，咱们直接动手就好。
先跟大家说下几个前提，本教程适合Ubuntu 20.04及以上版本，我亲测22.04和24.04都能正常用，服务器配置最好至少2核4G，网络要通畅，后续会用到的API密钥大家提前准备好，整个过程都用终端操作，所有命令直接复制粘贴就能执行，能避免手动输入出错。
一、部署前准备（必须做，少一步都不行）
部署前的准备工作主要有两点，就是更新系统依赖包和确认Node.js运行环境，因为Claude CodeUI运行离不开Node.js，而且它的版本得达到18.0及以上，这一步一定要做好，不然后续很可能出现各种安装失败的问题。
1. 更新系统包管理器
首先用快捷键Ctrl+Alt+T打开Ubuntu终端，执行下面的命令更新系统软件包，这样既能保证所有依赖都是最新版本，也能修复可能存在的破损包，防止后续安装时出现冲突。
命令1：更新软件包列表
sudo apt update && sudo apt upgrade -y
这里跟大家说下，sudo是用来获取管理员权限的，apt是Ubuntu自带的软件管理工具，update是更新软件包列表，upgrade是升级已经安装的软件包，加上-y参数就能自动确认所有升级操作，不用手动输y确认，能省不少时间。
要是执行过程中出现“软件包冲突”“破损包”这类提示，直接执行下面的命令修复，修复好之后重新执行上面的更新命令就能继续操作了。
sudo apt --fix-broken install
2. 安装/验证Node.js环境
Claude CodeUI运行必须用到Node.js，而且版本不能低于18.0，大家先执行下面的命令检查系统有没有安装这个软件，以及它的版本是否符合要求。
执行命令：node --version && npm --version
如果显示的Node.js版本在18.0及以上，比如v18.17.0、v20.10.0，而且npm版本正常，就说明环境符合要求，直接跳过安装步骤进入下一步就行。
要是显示“command not found”就说明系统没装Node.js，要是版本低于18.0就说明版本不够，这两种情况都需要重新安装。
咱们用20.x版本来安装，这个版本比较稳定，和Claude CodeUI也适配，大家直接执行下面的两条命令就行。
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -
sudo apt-get install -y nodejs
安装完成后再执行一次node --version && npm --version，确认版本符合要求就可以了，要是安装时出现“文件冲突”，比如提示“libnode-dev”和nodejs冲突，就先执行下面三条命令卸载旧版本，清理干净后再重新安装Node.js。
sudo apt-get remove --purge nodejs libnode-dev
sudo apt-get autoremove -y
sudo apt-get clean
3. 准备API密钥
Claude CodeUI得有API密钥才能正常用，大家提前弄好有效的密钥，具体怎么弄这里就不细说了，只要保证密钥能用就行，后续配置的时候会用到，建议大家提前复制保存好，别到时候反复切换窗口去找。
二、核心部署步骤（全程复制命令，不会出错）
准备工作都做好之后就进入核心部署环节了，整个过程分为三步，分别是安装Claude CodeUI、解决常见的启动报错和配置API密钥，每一步都有详细说明，大家跟着做就能完成。
1. 安装Claude CodeUI
大家在终端里执行下面的命令，通过npm全局安装Claude CodeUI，虽然有些新版本已经支持原生二进制安装，但npm安装更适合新手，兼容性也更好。
npm install -g @anthropic-ai/claude-code
要是之前安装过旧版本，就先执行下面的卸载命令，避免出现版本冲突。
npm uninstall -g @anthropic-ai/claude-code
安装的时候终端会显示进度，大家耐心等一会儿，安装完成后执行下面的命令检查是否安装成功，要是显示版本号比如v2.1.x就说明安装好了，要是提示“command not found”，重启终端后再执行检查命令就行。
claude --version
2. 解决启动报错（新手一定要看，避免踩坑）
很多新手安装完成后执行启动命令会报错，最常见的就是“Error: spawn xdg-open ENOENT”，这是因为系统少了xdg-utils这个工具，导致没法自动打开UI界面，大家执行下面的命令安装这个工具就能解决。
sudo apt install -y xdg-utils
除此之外还有一种常见报错是“找不到项目目录”，这是因为Claude CodeUI需要一个默认的项目配置目录，大家执行下面两条命令创建目录和配置文件就可以了。
mkdir -p /root/.claude/projects
touch /root/.claude/project-config.json
创建好之后大家可以简单初始化一下配置文件，这一步可以不做但建议做，执行下面的命令打开编辑界面，粘贴指定内容后按Ctrl+O保存、Ctrl+X退出，这样就能完成配置文件初始化，避免后续启动时出现目录缺失的报错。
nano /root/.claude/project-config.json
需要粘贴的内容：
{ "projects": [] }
3. 启动Claude CodeUI并配置API密钥
所有准备工作和报错处理都做好之后，大家执行下面的命令就能启动Claude CodeUI了。
npx lanyuncodingui
启动成功后系统会自动尝试打开浏览器界面，要是是服务器端部署没有图形界面，大家不用管浏览器打开失败的提示，重点看终端输出的端口信息就行，一般情况下UI界面的访问端口是3732或3876。
接下来就是配置API密钥，具体步骤很简单：进入Claude CodeUI界面后先创建账户，输入姓名再输两次密码就能创建完成，登录账户后点击左下角的Tools Settings进入设置界面，在里面找到API相关的配置项，粘贴提前准备好的API密钥并保存配置，最后返回主界面点击左上角的创建按钮，输入文件路径创建项目文件夹，到这里Claude CodeUI就部署完成，可以正常使用了。
三、启动与停止Claude CodeUI（日常使用要会）
部署完成后大家要知道怎么启动和停止Claude CodeUI，避免误操作导致服务出问题。
启动命令是npx lanyuncodingui，每次启动都要执行这个命令，而且启动后终端不能关，一关终端服务就停了；停止命令很简单，在启动服务的终端里按Ctrl+C就能停止服务。
另外跟大家补充一点，要是想让Claude CodeUI在后台运行，也就是关了终端也不影响服务，就执行命令nohup npx lanyuncodingui &，后台运行后要是想停止服务，需要先找到对应的进程再终止，不过这个操作新手暂时不用学，以后有需要再了解就好。
四、常见问题排查（新手避坑汇总）
这里给大家整理了部署过程中最常见的几个问题和对应的解决办法，大家遇到问题直接对照着排查，不用到处找答案。
第一个问题是执行npm install命令时报错“permission denied”，也就是权限不够，解决办法很简单，在命令前面加sudo，也就是sudo npm install -g @anthropic-ai/claude-code，获取管理员权限后再安装就行。
第二个问题是启动后UI界面打不开，终端提示“port already in use”，也就是端口被占用，大家可以找到占用这个端口的进程并终止，之后重新启动，也可以直接重启Ubuntu系统释放端口。
第三个问题是配置API密钥后不能正常使用，提示“API key invalid”，也就是API密钥无效，大家要检查一下密钥有没有复制对，别多复制空格或换行，确认密钥没过期后，重新粘贴配置并保存，再重启服务就可以了。
第四个问题是执行node --version时版本显示正常，但启动Claude CodeUI时还是提示“Node.js版本过低”，这种情况大家重启终端让系统识别最新的Node.js版本，或者重新安装Node.js，确保安装过程没有报错就可以解决。
五、总结
到这里，在Ubuntu系统上部署Claude CodeUI的全部过程就结束了，其实整个操作并不复杂，关键就是做好环境准备、解决常见报错和正确配置API密钥，对新手来说，最容易踩坑的地方就是Node.js版本不符、端口占用和API密钥配置错误，只要大家跟着这份教程一步步操作，每一步都复制命令执行，避开这些坑就能顺利完成部署。
要是大家在部署过程中遇到其他问题，欢迎在评论区留言，我会第一时间回复解决，另外部署完成后大家可以试着创建项目、上传代码，感受一下Claude CodeUI的强大功能，以后我也会分享更多它的使用技巧，大家记得关注哦。