216 lines
11 KiB
Markdown
216 lines
11 KiB
Markdown
# Linux版Claude桌面客户端
|
||
|
||
`Claude` `Linux` `桌面应用` `Electron` `MCP`
|
||
|
||
# Linux 版 Claude Desktop
|
||
|
||
本项目提供构建脚本，用于在 Linux 系统上原生运行 Claude Desktop。它将官方 Windows 应用重新打包为适用于 Linux 发行版的格式，支持 `.deb` 包（Debian/Ubuntu）、`.rpm` 包（Fedora/RHEL）、发行版无关的 AppImage、适用于 Arch Linux 的 [AUR 包](https://aur.archlinux.org/packages/claude-desktop-appimage)，以及适用于 NixOS 的 Nix flake。
|
||
|
||
**注意：** 这是一个非官方构建脚本。如需官方支持，请访问 [Anthropic 官网](https://www.anthropic.com)。如遇构建脚本或 Linux 实现方面的问题，请在本仓库 [提交 Issue](https://github.com/aaddrick/claude-desktop-debian/issues)。
|
||
|
||
---
|
||
|
||
> **⚠️ 实验性功能：协作模式支持**
|
||
> 本构建默认**启用**协作模式，并支持可插拔的隔离后端：
|
||
>
|
||
> | 后端 | 隔离方式 | 依赖要求 |
|
||
> |------|----------|----------|
|
||
> | **bubblewrap**（默认） | 命名空间沙箱 | 需安装并可用 `bwrap` |
|
||
> | **host**（回退） | 无隔离，直接运行在宿主机上 | 无额外要求 |
|
||
>
|
||
> 启动时会自动检测最佳可用后端。运行 `claude-desktop --doctor` 可查看将使用哪个后端以及缺少哪些依赖。
|
||
>
|
||
> **注意：** bubblewrap 后端以只读方式挂载你的主目录（仅项目工作目录可写）。host 后端不提供任何隔离——仅在充分了解安全风险的情况下使用。
|
||
>
|
||
> **KVM 状态：** KVM/QEMU 后端代码已存在但尚不可用——为防止校验和循环问题（#337），Linux 上已禁用虚拟机文件下载。该后端代码保留以备将来使用。
|
||
|
||
---
|
||
|
||
## 功能特性
|
||
|
||
- **原生 Linux 支持**：无需虚拟化或 Wine 即可运行 Claude Desktop
|
||
- **MCP 支持**：完整的模型上下文协议集成
|
||
配置文件路径：`~/.config/Claude/claude_desktop_config.json`
|
||
- **系统集成**：
|
||
- 全局快捷键支持（Ctrl+Alt+Space）——在 X11 和 Wayland（通过 XWayland）上均可使用
|
||
- 系统托盘集成
|
||
- 桌面环境集成
|
||
|
||
### 截图
|
||
|
||
<p align="center">
|
||
<img src="https://raw.githubusercontent.com/aaddrick/claude-desktop-debian/main/docs/images/claude-desktop-screenshot1.png" alt="在 Linux 上运行的 Claude Desktop" />
|
||
</p>
|
||
|
||
<p align="center">
|
||
<img src="https://raw.githubusercontent.com/aaddrick/claude-desktop-debian/main/docs/images/claude-desktop-screenshot2.png" alt="全局快捷键弹窗" />
|
||
</p>
|
||
|
||
## 安装方式
|
||
|
||
### 使用 APT 仓库（Debian/Ubuntu - 推荐）
|
||
|
||
添加仓库以通过 `apt` 自动更新：
|
||
|
||
```bash
|
||
# 添加 GPG 密钥
|
||
curl -fsSL https://aaddrick.github.io/claude-desktop-debian/KEY.gpg | sudo gpg --dearmor -o /usr/share/keyrings/claude-desktop.gpg
|
||
|
||
# 添加仓库
|
||
echo "deb [signed-by=/usr/share/keyrings/claude-desktop.gpg arch=amd64,arm64] https://aaddrick.github.io/claude-desktop-debian stable main" | sudo tee /etc/apt/sources.list.d/claude-desktop.list
|
||
|
||
# 更新并安装
|
||
sudo apt update
|
||
sudo apt install claude-desktop
|
||
```
|
||
|
||
后续更新将随系统常规更新（`sudo apt upgrade`）自动安装。
|
||
|
||
### 使用 DNF 仓库（Fedora/RHEL - 推荐）
|
||
|
||
添加仓库以通过 `dnf` 自动更新：
|
||
|
||
```bash
|
||
# 添加仓库
|
||
sudo curl -fsSL https://aaddrick.github.io/claude-desktop-debian/rpm/claude-desktop.repo -o /etc/yum.repos.d/claude-desktop.repo
|
||
|
||
# 安装
|
||
sudo dnf install claude-desktop
|
||
```
|
||
|
||
后续更新将随系统常规更新（`sudo dnf upgrade`）自动安装。
|
||
|
||
### 使用 AUR（Arch Linux）
|
||
|
||
[`claude-desktop-appimage`](https://aur.archlinux.org/packages/claude-desktop-appimage) 包已发布在 AUR，每次发布时自动更新。
|
||
|
||
```bash
|
||
# 使用 yay
|
||
yay -S claude-desktop-appimage
|
||
|
||
# 或使用 paru
|
||
paru -S claude-desktop-appimage
|
||
```
|
||
|
||
AUR 包安装的是 AppImage 格式的 Claude Desktop。
|
||
|
||
### 使用 Nix Flake（NixOS）
|
||
|
||
直接从 flake 安装：
|
||
|
||
```bash
|
||
# 基础安装
|
||
nix profile install github:aaddrick/claude-desktop-debian
|
||
|
||
# 支持 MCP 服务器（FHS 环境）
|
||
nix profile install github:aaddrick/claude-desktop-debian#claude-desktop-fhs
|
||
```
|
||
|
||
或添加到 NixOS 配置中：
|
||
|
||
```nix
|
||
# flake.nix
|
||
{
|
||
inputs.claude-desktop.url = "github:aaddrick/claude-desktop-debian";
|
||
|
||
outputs = { nixpkgs, claude-desktop, ... }: {
|
||
nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
|
||
modules = [
|
||
({ pkgs, ... }: {
|
||
nixpkgs.overlays = [ claude-desktop.overlays.default ];
|
||
environment.systemPackages = [ pkgs.claude-desktop ];
|
||
})
|
||
];
|
||
};
|
||
};
|
||
}
|
||
```
|
||
|
||
### 使用预构建发布包
|
||
|
||
从 [Releases 页面](https://github.com/aaddrick/claude-desktop-debian/releases) 下载最新的 `.deb`、`.rpm` 或 `.AppImage`。
|
||
|
||
### 从源码构建
|
||
|
||
详细构建说明请参阅 [docs/BUILDING.md](docs/BUILDING.md)。
|
||
|
||
## 配置
|
||
|
||
模型上下文协议设置存储在：
|
||
```
|
||
~/.config/Claude/claude_desktop_config.json
|
||
```
|
||
|
||
有关环境变量和 Wayland 支持等其他配置选项，请参阅 [docs/CONFIGURATION.md](docs/CONFIGURATION.md)。
|
||
|
||
## 故障排查
|
||
|
||
运行 `claude-desktop --doctor` 可使用内置诊断工具，检查常见问题（显示服务器、沙箱权限、MCP 配置、残留锁文件等）。同时还会报告协作模式就绪情况——将使用哪个隔离后端，以及哪些依赖（KVM、QEMU、vsock、socat、virtiofsd、bubblewrap）已安装或缺失。
|
||
|
||
更多故障排查方法、卸载说明和日志路径，请参阅 [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)。
|
||
|
||
## 致谢
|
||
|
||
本项目受 [k3d3 的 claude-desktop-linux-flake](https://github.com/k3d3/claude-desktop-linux-flake) 及其关于在 Linux 上原生运行 Claude Desktop 的 [Reddit 帖子](https://www.reddit.com/r/ClaudeAI/comments/1hgsmpq/i_successfully_ran_claude_desktop_natively_on/) 启发。
|
||
|
||
特别感谢：
|
||
- **k3d3**：提供原始 NixOS 实现和原生绑定思路
|
||
- **[emsi](https://github.com/emsi/claude-desktop)**：提供标题栏修复和替代实现方案
|
||
- **[leobuskin](https://github.com/leobuskin/unofficial-claude-desktop-linux)**：提供基于 Playwright 的 URL 解析方案
|
||
- **[yarikoptic](https://github.com/yarikoptic)**：提供 codespell 支持和 shellcheck 合规性改进
|
||
- **[IamGianluca](https://github.com/IamGianluca)**：改进构建依赖检查
|
||
- **[ing03201](https://github.com/ing03201)**：提供 IBus/Fcitx5 输入法支持
|
||
- **[ajescudero](https://github.com/ajescudero)**：固定 @electron/asar 版本以兼容 Node
|
||
- **[delorenj](https://github.com/delorenj)**：提供 Wayland 兼容性支持
|
||
- **[Regen-forest](https://github.com/Regen-forest)**：建议使用 Gear Lever 替代 AppImageLauncher
|
||
- **[niekvugteveen](https://github.com/niekvugteveen)**：修复 Debian 打包权限问题
|
||
- **[speleoalex](https://github.com/speleoalex)**：提供原生窗口装饰支持
|
||
- **[imaginalnika](https://github.com/imaginalnika)**：将日志移至 `~/.cache/`
|
||
- **[richardspicer](https://github.com/richardspicer)**：修复 Linux 上菜单栏可见性问题
|
||
- **[jacobfrantz1](https://github.com/jacobfrantz1)**：提供 Claude Desktop 代码预览支持及快速窗口提交修复
|
||
- **[janfrederik](https://github.com/janfrederik)**：添加 `--exe` 标志以使用本地安装程序
|
||
- **[MrEdwards007](https://github.com/MrEdwards007)**：发现 OAuth 令牌缓存修复方案
|
||
- **[lizthegrey](https://github.com/lizthegrey)**：贡献版本更新
|
||
- **[mathys-lopinto](https://github.com/mathys-lopinto)**：提供 AUR 包和自动化部署
|
||
- **[pkuijpers](https://github.com/pkuijpers)**：分析 RPM 仓库 GPG 签名问题的根本原因
|
||
- **[dlepold](https://github.com/dlepold)**：发现托盘图标变量名 Bug 并提供可用修复
|
||
- **[Voork1144](https://github.com/Voork1144)**：详细分析托盘图标压缩器 Bug、Chromium 布局缓存 Bug 的根本原因，以及直接子元素 `setBounds()` 修复方案
|
||
- **[sabiut](https://github.com/sabiut)**：提供 `--doctor` 诊断命令及下载 SHA-256 校验和验证
|
||
- **[milog1994](https://github.com/milog1994)**：改善 Linux 用户体验，包括弹窗检测、功能桩和 Wayland 混成器支持
|
||
- **[jarrodcolburn](https://github.com/jarrodcolburn)**：提供容器/CI 环境中无密码 sudo 支持、识别 gh-pages 4GB 膨胀修复、识别 Debian 上 virtiofsd PATH 检测问题、详细分析 runner 被终止导致的 CI 发布流水线故障，以及诊断 session-start hook sudo 阻塞问题并给出三种解决方案
|
||
- **[chukfinley](https://github.com/chukfinley)**：提供 Linux 实验性协作模式支持
|
||
- **[CyPack](https://github.com/CyPack)**：启动时清理孤立的协作守护进程
|
||
- **[IliyaBrook](https://github.com/IliyaBrook)**：修复 Claude Desktop >= 1.1.3541 arm64 重构的平台补丁
|
||
- **[MichaelMKenny](https://github.com/MichaelMKenny)**：诊断 `$` 前缀 electron 变量 Bug，提供根本原因分析和临时方案
|
||
- **[daa25209](https://github.com/daa25209)**：详细分析协作平台门控崩溃的根本原因并提供补丁脚本
|
||
- **[noctuum](https://github.com/noctuum)**：提供 `CLAUDE_MENU_BAR` 环境变量，支持可配置菜单栏可见性及布尔别名
|
||
- **[typedrat](https://github.com/typedrat)**：提供 NixOS flake 与 build.sh 集成、node-pty 派生、CI 自动更新，并修复 flake 包作用域回归问题
|
||
- **[cbonnissent](https://github.com/cbonnissent)**：逆向工程协作虚拟机客户端 RPC 协议、修复 KVM 启动阻塞问题，以及修复持久连接的 RPC 响应 id 回显问题
|
||
- **[joekale-pp](https://github.com/joekale-pp)**：为 RPM 启动器添加 `--doctor` 支持
|
||
- **[ecrevisseMiroir](https://github.com/ecrevisseMiroir)**：提供基于 tmpfs 最小根的 bwrap 后端沙箱隔离
|
||
- **[arauhala](https://github.com/arauhala)**：详细分析 NixOS `isPackaged` 回归问题的根本原因
|
||
- **[cromagnone](https://github.com/cromagnone)**：通过详细日志确认 bwrap 安装中的虚拟机下载循环问题，推翻了最初的分类判断
|
||
- **[aHk-coder](https://github.com/aHk-coder)**：诊断协作 smol-bin 补丁中硬编码压缩变量导致的崩溃问题
|
||
- **[RayCharlizard](https://github.com/RayCharlizard)**：详细分析 `.mcpb-cache` 自引用符号链接 ELOOP Bug
|
||
- **[reinthal](https://github.com/reinthal)**：修复 nixpkgs 移除 `nodePackages` 导致的 NixOS 构建失败
|
||
- **[gianluca-peri](https://github.com/gianluca-peri)**：报告 GNOME 退出可访问性问题，并确认 AppIndicator 的托盘行为
|
||
|
||
## 赞助
|
||
|
||
Anthropic 不发布 Claude Desktop 的更新日志。本项目每次发布时都包含 AI 生成的说明，分析两个版本之间的代码变化。如果你感兴趣，我写了一篇关于该流程的文章：[从压缩的 Electron 应用生成真实发布说明](https://nonconvexlabs.com/blog/generating-real-release-notes-from-minified-electron-apps)。
|
||
|
||
分析过程会调用 Claude 的 API，费用因更新规模差异较大。近期每次发布的费用在 **3.36 美元至 76.16 美元**之间。
|
||
|
||
如果本项目对你有帮助，欢迎通过 [GitHub Sponsors](https://github.com/sponsors/aaddrick) 赞助，以帮助分担这些费用。
|
||
|
||
## 许可证
|
||
|
||
本仓库中的构建脚本采用双重许可：
|
||
- MIT 许可证（见 [LICENSE-MIT](LICENSE-MIT)）
|
||
- Apache 许可证 2.0（见 [LICENSE-APACHE](LICENSE-APACHE)）
|
||
|
||
Claude Desktop 应用本身受 [Anthropic 消费者条款](https://www.anthropic.com/legal/consumer-terms)约束。
|
||
|
||
## 贡献
|
||
|
||
欢迎贡献代码！提交贡献即表示你同意以与本项目相同的双重许可条款授权你的贡献。 |