wehub-resource-sync
201 lines
10 KiB
Markdown
201 lines
10 KiB
Markdown
<!-- WEHUB_ZH_README -->
|
||
> [!NOTE]
|
||
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
|
||
> [English](./README.en.md) · [原始项目](https://github.com/aaddrick/claude-desktop-debian) · [上游 README](https://github.com/aaddrick/claude-desktop-debian/blob/HEAD/README.md)
|
||
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
|
||
|
||
# Claude Desktop for Linux
|
||
|
||
本项目将 Claude Desktop 重新打包为 Anthropic 自身不提供的 Linux 格式：`.rpm`（Fedora/RHEL）、与发行版无关的 AppImage、面向 NixOS 的 Nix flake，以及适用于 Arch 的 [AUR 软件包](https://aur.archlinux.org/packages/claude-desktop-appimage)。
|
||
|
||
2026 年 6 月 30 日，Anthropic 发布了官方第一方 Claude Desktop for Linux 测试版，以 `.deb`（amd64 与 arm64）形式从其自有 APT 软件源分发。自 v3.0.0 起，本项目重新打包该官方 Linux `.deb`，不再重新打包 Windows 安装程序。
|
||
|
||
官方 `.deb` 仅覆盖一种打包目标。它所未涵盖的是一长串发行版、桌面环境与会话类型——详见本项目 issue 历史中整理的[已报告环境调查](docs/reports/CDL-ANT-0009_patch-suite-history/reported-environments/grouped-families.md)。这一长尾场景正是本项目的服务对象；此外还提供启动器，以及针对 Linux 环境怪癖的 `--doctor`。[安装](#installation)一节说明了哪些由我们提供、哪些来自上游。
|
||
|
||
**注意：** 这是一个非官方的重新打包项目。如需官方支持，请访问 [Anthropic 官网](https://www.anthropic.com).。有关打包或 Linux 启动器的问题，请在此[提交 issue](https://github.com/aaddrick/claude-desktop-debian/issues)。
|
||
|
||
**文档：** 完整文档见 [`docs/index.md`](docs/index.md)。发布历史见 [`CHANGELOG.md`](CHANGELOG.md)。贡献指南：[`CONTRIBUTING.md`](CONTRIBUTING.md)。安全报告：[`SECURITY.md`](SECURITY.md)。
|
||
|
||
---
|
||
|
||
## 功能特性
|
||
|
||
- **官方应用，额外格式**：将 Anthropic 官方 Linux `.deb` 重新打包为 `.rpm`、AppImage 与 AUR 构建。
|
||
- **MCP 支持**：完整的 Model Context Protocol（MCP）集成。配置位于 `~/.config/Claude/claude_desktop_config.json`（参见[配置](#configuration)）。
|
||
- **面向 Linux 怪癖的启动器**：可选的原生 Wayland（`CLAUDE_USE_WAYLAND=1`）、GPU 崩溃自动恢复、XRDP 检测、输入法（IM）模块覆盖，以及自启动项修复。
|
||
- **`--doctor` 诊断**：检查显示服务器、沙箱权限、MCP 配置、陈旧锁、KVM/Cowork 栈，以及官方版本漂移。
|
||
- **Linux 上的 Cowork**：在 KVM（硬件虚拟化）可用时运行。doctor 会报告就绪状态。
|
||
- **系统集成**：X11 与 Wayland 上的全局快捷键（Ctrl+Alt+Space）、系统托盘，以及桌面环境集成。
|
||
|
||
### 截图
|
||
|
||
<p align="center">
|
||
<img src="https://raw.githubusercontent.com/aaddrick/claude-desktop-debian/main/docs/images/claude-desktop-screenshot1.png" alt="Claude Desktop running on Linux" />
|
||
</p>
|
||
|
||
<p align="center">
|
||
<img src="https://raw.githubusercontent.com/aaddrick/claude-desktop-debian/main/docs/images/claude-desktop-screenshot2.png" alt="Global hotkey popup" />
|
||
</p>
|
||
|
||
## 安装
|
||
|
||
Anthropic 提供 `.deb`。我们提供其余一切。自 v3.0.0 起，我们的软件包命名为 `claude-desktop-unofficial`，因此可与 Anthropic 官方 `claude-desktop` 并排安装——但二者共享 `~/.config/Claude`，因此同一时间只能运行一个。分工如下：
|
||
|
||
| 格式 | 提供方 |
|
||
|--------|---------------|
|
||
| `.deb`（Debian/Ubuntu，amd64 + arm64） | Anthropic 官方 APT 源。我们以 `claude-desktop-unofficial` 镜像（附加启动器与 doctor），可与官方软件包并存。 |
|
||
| `.rpm`（Fedora/RHEL） | 本项目。 |
|
||
| AppImage（任意发行版） | 本项目。 |
|
||
| AUR（Arch） | 本项目（构建 AppImage）。 |
|
||
| Nix flake（NixOS） | 本项目。 |
|
||
|
||
除打包之外，我们构建的每种格式均包含：
|
||
|
||
- **我们的启动器。** 通过 `CLAUDE_USE_WAYLAND=1` 可选启用原生 Wayland、GPU 崩溃自动恢复、XRDP 检测、IM 模块覆盖，以及自启动项修复。
|
||
- **`claude-desktop-unofficial --doctor`。** 针对 KVM/Cowork 栈、官方版本漂移、名称冲突与配置问题的诊断。
|
||
- **打包修复。** Cowork 所需的 RPM 固件兼容符号链接，以及 Ubuntu 24.04+ AppArmor 配置文件。
|
||
|
||
应用本体为官方 `app.asar`，除两处填补 Linux 缺口的小补丁外字节级一致：面向 KDE 的 Quick Entry 焦点修复（待上游合并），以及 Linux 上游缺失的 org-plugins 路径修复。
|
||
|
||
### 使用 APT 软件源（Debian/Ubuntu — 推荐）
|
||
|
||
添加软件源以通过 `apt` 自动更新：
|
||
|
||
```bash
|
||
# Add the GPG key
|
||
curl -fsSL https://pkg.claude-desktop-debian.dev/KEY.gpg | sudo gpg --dearmor -o /usr/share/keyrings/claude-desktop-unofficial.gpg
|
||
|
||
# Add the repository
|
||
echo "deb [signed-by=/usr/share/keyrings/claude-desktop-unofficial.gpg arch=amd64,arm64] https://pkg.claude-desktop-debian.dev stable main" | sudo tee /etc/apt/sources.list.d/claude-desktop-unofficial.list
|
||
|
||
# Update and install
|
||
sudo apt update
|
||
sudo apt install claude-desktop-unofficial
|
||
```
|
||
|
||
后续更新将随常规系统更新自动安装（`sudo apt upgrade`）。
|
||
|
||
### 使用 DNF 软件源（Fedora/RHEL — 推荐）
|
||
|
||
添加软件源以通过 `dnf` 自动更新：
|
||
|
||
```bash
|
||
# Add the repository
|
||
sudo curl -fsSL https://pkg.claude-desktop-debian.dev/rpm/claude-desktop-unofficial.repo -o /etc/yum.repos.d/claude-desktop-unofficial.repo
|
||
|
||
# Install
|
||
sudo dnf install claude-desktop-unofficial
|
||
```
|
||
|
||
后续更新将随常规系统更新自动安装（`sudo dnf upgrade`）。
|
||
|
||
### 使用 AUR（Arch Linux）
|
||
|
||
[`claude-desktop-appimage`](https://aur.archlinux.org/packages/claude-desktop-appimage) 软件包可在 AUR 获取，并随每次发布自动更新。
|
||
|
||
```bash
|
||
# Using yay
|
||
yay -S claude-desktop-appimage
|
||
|
||
# Or using paru
|
||
paru -S claude-desktop-appimage
|
||
```
|
||
|
||
AUR 软件包安装的是 Claude Desktop 的 AppImage 构建。
|
||
|
||
### 使用 Nix Flake（NixOS）
|
||
|
||
直接从 flake 安装：
|
||
|
||
```bash
|
||
# Basic install
|
||
nix profile install github:aaddrick/claude-desktop-debian
|
||
|
||
# With MCP server support (FHS environment)
|
||
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)。
|
||
|
||
## 配置
|
||
|
||
Model Context Protocol（MCP）设置保存在：
|
||
```
|
||
~/.config/Claude/claude_desktop_config.json
|
||
```
|
||
|
||
**在手动编辑此文件之前，请先退出 Claude Desktop，然后重新打开。** 应用在运行时会重写自身配置，因此在应用打开时所做的编辑会在下次写入时被覆盖。先退出，再编辑，然后重新启动。启动时加载的服务器在重启后仍可正常工作——这只影响针对正在运行应用进行的手动编辑。
|
||
|
||
有关环境变量、Wayland 支持等其他配置选项，见 [docs/configuration.md](docs/configuration.md)。
|
||
|
||
## 故障排除
|
||
|
||
运行 `claude-desktop-unofficial --doctor` 进行内置诊断。它会检查常见疑点：显示服务器、沙箱权限、MCP 配置、陈旧锁等。它还会报告 Cowork 就绪状态。Linux 上的 Cowork 运行在 KVM 支持的虚拟机中，因此 doctor 会报告其依赖项（KVM、QEMU、OVMF 固件、vhost-vsock、virtiofsd）中哪些已安装、哪些缺失。
|
||
|
||
更多故障排除、卸载说明与日志位置，见 [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 实现
|
||
- 关于原生绑定（native bindings）的见解
|
||
- **[emsi](https://github.com/emsi/claude-desktop)**
|
||
- 标题栏修复
|
||
- 替代实现方案
|
||
- **[leobuskin](https://github.com/leobuskin/unofficial-claude-desktop-linux)** 贡献了基于 Playwright 的 URL 解析方案
|
||
|
||
完整的贡献者致谢列表——所有通过 PR、修复或分析塑造了本项目的成员，按时间顺序排列——见 [ACKNOWLEDGMENTS.md](ACKNOWLEDGMENTS.md)。
|
||
|
||
## 赞助
|
||
|
||
如果本项目对你有帮助，请考虑 [在 GitHub 上赞助](https://github.com/sponsors/aaddrick).
|
||
|
||
## 许可证
|
||
|
||
本仓库中的构建脚本采用双重许可：
|
||
- MIT License（参见 [LICENSE-MIT](LICENSE-MIT)）
|
||
- Apache License 2.0（参见 [LICENSE-APACHE](LICENSE-APACHE)）
|
||
|
||
Claude Desktop 应用本身受 [Anthropic's Consumer Terms](https://www.anthropic.com/legal/consumer-terms). 约束
|
||
|
||
## 隐私
|
||
|
||
本仓库使用自动化分类机器人（triage bot），当你提交 bug 报告或功能请求时，会将 issue 内容发送至 Anthropic API 进行分类与调查。该机器人会读取 issue 正文、标题以及任何被引用的相关 issue；它不会跟随 URL、执行代码块，也不会读取触发该 issue 之外的内容。
|
||
|
||
请勿包含凭据、令牌、个人数据或任何你不会公开发布在公开 issue 跟踪器上的内容。如果你发布了敏感内容后又将其编辑删除，机器人最初读取的内容会作为运行产物保留以供审计——GitHub 界面会隐藏编辑，但维护者可恢复机器人所看到的内容。
|
||
|
||
完整设计与数据清单：[`docs/issue-triage/README.md`](docs/issue-triage/README.md)。
|
||
|
||
## 贡献
|
||
|
||
欢迎贡献！提交贡献即表示你同意按照与本项目相同的双重许可条款进行授权。
|