安装指南

选择你的操作系统，按照步骤完成 Mantra 安装。

关于下载链接

本文档中的下载链接（mantra.gonewx.com/download）将在产品正式发布后生效。目前请关注官方公告获取最新下载地址。

系统要求概览

在开始安装之前，请确认你的系统满足以下要求：

操作系统	最低版本	架构	磁盘空间
macOS	10.15 (Catalina)	Intel / Apple Silicon	~100MB
Windows	10	64 位	~100MB
Linux	Ubuntu 18.04+ / Fedora 32+ / Debian 10+	64 位	~100MB

macOS 安装

系统要求

操作系统: macOS 10.15 (Catalina) 或更高版本
处理器: Intel 或 Apple Silicon (M1/M2/M3/M4)
磁盘空间: 约 100MB 可用空间
权限: 需要管理员权限安装

方式一：下载 DMG 安装包（推荐）

这是最简单的安装方式，适合大多数用户。

下载安装包
访问 Mantra 官网下载页面，选择 macOS 版本下载 .dmg 文件。
选择正确的版本
- Apple Silicon (M1/M2/M3/M4): 下载 Mantra-x.x.x-arm64.dmg
- Intel Mac: 下载 Mantra-x.x.x-x64.dmg
不确定你的 Mac 类型？点击左上角 → "关于本机"，查看"芯片"或"处理器"信息。
💡 文件名中的 x.x.x 代表版本号，请以实际下载页面显示的版本为准。
打开安装包
双击下载的 .dmg 文件，将出现安装窗口。
安装应用
将 Mantra 图标拖拽到 Applications（应用程序）文件夹。
首次启动
打开"应用程序"文件夹，找到 Mantra 并双击启动。
首次启动安全提示
首次打开时，macOS 可能显示"无法打开，因为无法验证开发者"的提示。
解决方法：
1. 右键点击 Mantra 应用图标
2. 选择"打开"
3. 在弹出对话框中点击"打开"
这个操作只需执行一次，后续可正常打开。

方式二：使用 Homebrew（暂未发布）

暂未发布

Homebrew 安装方式正在准备中，敬请期待。目前请使用官网下载 DMG 安装包。

如果你已安装 Homebrew，可以通过命令行快速安装：

bash

brew install --cask mantra

Homebrew 安装的优势

一条命令完成安装
方便后续更新：brew upgrade --cask mantra
统一管理所有应用

更新 Mantra：

bash

brew upgrade --cask mantra

卸载 Mantra：

bash

brew uninstall --cask mantra

Windows 安装

系统要求

操作系统: Windows 10 或更高版本
架构: 64 位系统
磁盘空间: 约 100MB 可用空间
权限: 需要管理员权限安装

如何确认系统架构

按 Win + I 打开设置 → 系统 → 关于，查看"系统类型"是否显示"64 位操作系统"。

方式一：下载安装程序（推荐）

下载安装程序
访问 Mantra 官网下载页面，下载 Windows 安装程序 Mantra-Setup-x.x.x.exe。
运行安装程序
双击下载的 .exe 文件，启动安装向导。
Windows SmartScreen 提示
首次运行时，Windows SmartScreen 可能显示"Windows 已保护你的电脑"提示。
解决方法：
1. 点击"更多信息"
2. 点击"仍要运行"
这是因为应用尚未获得 Windows 签名认证，但下载自官网是安全的。
完成安装
按照安装向导提示，选择安装位置并完成安装。
启动 Mantra
安装完成后，可以通过以下方式启动：
- 从开始菜单搜索"Mantra"
- 双击桌面快捷方式（如已创建）

方式二：使用 Scoop（暂未发布）

暂未发布

Scoop 安装方式正在准备中，敬请期待。目前请使用官网下载安装程序。

Scoop 是 Windows 上的命令行安装器。如果你已安装 Scoop：

powershell

scoop bucket add extras
scoop install mantra

更新 Mantra：

powershell

scoop update mantra

卸载 Mantra：

powershell

scoop uninstall mantra

方式三：使用 Winget（暂未发布）

暂未发布

Winget 安装方式正在准备中，敬请期待。目前请使用官网下载安装程序。

Windows 10/11 内置的包管理器 Winget：

powershell

winget install Mantra.Mantra

更新 Mantra：

powershell

winget upgrade Mantra.Mantra

卸载 Mantra：

powershell

winget uninstall Mantra.Mantra

Linux 安装

系统要求

发行版: Ubuntu 18.04+, Debian 10+, Fedora 32+, Arch Linux, 或其他主流发行版
架构: 64 位 (x86_64)
磁盘空间: 约 100MB 可用空间
依赖: GTK 3, libnotify（大多数桌面发行版已预装）

方式一：AppImage（推荐，无需安装）

AppImage 是一种便携式应用格式，无需安装即可运行，适用于所有 Linux 发行版。

下载 AppImage
访问 Mantra 官网下载页面，下载 Mantra-x.x.x.AppImage。
添加执行权限
bash
```
chmod +x Mantra-x.x.x.AppImage
```
运行应用
bash
```
./Mantra-x.x.x.AppImage
```

AppImage 的优势

无需 root 权限
不影响系统其他软件
便于尝试不同版本
可放在任意位置运行

方式二：DEB 包（暂未发布）

暂未发布

DEB 包及 APT 软件源正在准备中，敬请期待。目前请使用 AppImage。

适用于 Debian、Ubuntu、Linux Mint 等基于 Debian 的发行版。

bash

# 下载 DEB 包
wget https://mantra.gonewx.com/download/mantra_x.x.x_amd64.deb

# 安装
sudo dpkg -i mantra_x.x.x_amd64.deb

# 如果有依赖问题，运行
sudo apt-get install -f

或使用 apt 直接安装（如果已添加软件源）：

bash

# 添加 GPG 密钥
curl -fsSL https://mantra.gonewx.com/gpg-key.asc | sudo gpg --dearmor -o /usr/share/keyrings/mantra-archive-keyring.gpg

# 添加软件源
echo "deb [signed-by=/usr/share/keyrings/mantra-archive-keyring.gpg] https://mantra.gonewx.com/apt stable main" | sudo tee /etc/apt/sources.list.d/mantra.list

# 更新并安装
sudo apt update
sudo apt install mantra

方式三：RPM 包（暂未发布）

暂未发布

RPM 包正在准备中，敬请期待。目前请使用 AppImage。

适用于 Fedora、RHEL、CentOS、openSUSE 等使用 RPM 的发行版。

bash

# 下载 RPM 包
wget https://mantra.gonewx.com/download/mantra-x.x.x.x86_64.rpm

# Fedora/RHEL 8+
sudo dnf install ./mantra-x.x.x.x86_64.rpm

# CentOS 7/旧版 RHEL
sudo yum localinstall ./mantra-x.x.x.x86_64.rpm

方式四：AUR（暂未发布）

暂未发布

AUR 包正在准备中，敬请期待。目前请使用 AppImage。

Arch Linux 用户可以从 AUR 安装：

bash

# 使用 yay
yay -S mantra-bin

# 或使用 paru
paru -S mantra-bin

方式五：Flatpak（暂未发布）

暂未发布

Flatpak 安装方式正在准备中，敬请期待。目前请使用 AppImage。

如果你的系统支持 Flatpak：

bash

flatpak install flathub dev.mantra.Mantra

运行：

bash

flatpak run dev.mantra.Mantra

方式六：Snap（暂未发布）

暂未发布

Snap 安装方式正在准备中，敬请期待。目前请使用 AppImage。

如果你的系统支持 Snap：

bash

sudo snap install mantra

安装验证

安装完成后，请验证 Mantra 是否正确安装。

启动应用

启动 Mantra，你应该能看到欢迎界面：

版本检查

如果 Mantra 提供命令行工具，可以通过以下命令验证安装：

macOS/LinuxWindows

bash

mantra --version

powershell

mantra --version

成功安装后，应显示类似以下输出：

Mantra version x.x.x

确认安装成功的标志

[x] 应用能够正常启动
[x] 欢迎界面正确显示
[x] 可以创建新项目或打开现有项目

故障排除

macOS 常见问题

"Mantra" 无法打开，因为无法验证开发者

原因：macOS Gatekeeper 安全机制阻止了未签名的应用。

解决方案：

右键点击 Mantra 应用
选择"打开"
在弹出对话框中点击"打开"

或者在系统偏好设置中：

打开"系统偏好设置" → "安全性与隐私"
在"通用"标签下，点击"仍要打开"

"Mantra" 已损坏，无法打开

原因：某些下载工具可能损坏文件的扩展属性。

解决方案：在终端中运行以下命令移除隔离属性：

bash

xattr -cr /Applications/Mantra.app

Apple Silicon Mac 启动缓慢或无法启动

原因：可能下载了 Intel 版本而不是 ARM 版本。

解决方案：确保下载对应 Apple Silicon 的版本（文件名包含 arm64）。

Windows 常见问题

Windows SmartScreen 阻止运行

原因：应用尚未获得 Microsoft 的签名认证。

解决方案：

点击"更多信息"链接
点击"仍要运行"按钮

确保从官网下载以保证安全。

安装时显示"此应用无法在你的电脑上运行"

原因：可能下载了错误的版本，或系统不是 64 位。

解决方案：

确认系统是 64 位（设置 → 系统 → 关于）
重新下载正确版本的安装程序

缺少 VCRUNTIME140.dll 或其他 DLL 文件

原因：缺少 Visual C++ 运行时库。

解决方案：下载并安装 Microsoft Visual C++ Redistributable。

Linux 常见问题

AppImage 无法运行

原因：未添加执行权限或缺少 FUSE。

解决方案：

bash

# 添加执行权限
chmod +x Mantra-x.x.x.AppImage

# 如果仍然无法运行，安装 FUSE
# Ubuntu/Debian
sudo apt install fuse libfuse2

# Fedora
sudo dnf install fuse fuse-libs

DEB/RPM 包安装后无法启动

原因：可能缺少依赖。

解决方案：

bash

# Debian/Ubuntu - 修复依赖
sudo apt-get install -f

# Fedora - 检查依赖
sudo dnf check

# 查看详细错误
mantra --verbose

显示问题（界面模糊或缩放异常）

原因：高 DPI 屏幕缩放问题。

解决方案：尝试使用以下环境变量启动：

bash

# 方法 1：强制缩放
GDK_SCALE=2 ./Mantra-x.x.x.AppImage

# 方法 2：禁用自动 DPI 缩放
QT_AUTO_SCREEN_SCALE_FACTOR=0 ./Mantra-x.x.x.AppImage

卸载说明

macOS 卸载

手动卸载：

退出 Mantra 应用
打开 Finder → 应用程序
将 Mantra 拖到废纸篓

（可选）删除配置文件：

bash

rm -rf ~/Library/Application\ Support/Mantra
rm -rf ~/Library/Preferences/dev.mantra.Mantra.plist

使用 Homebrew 卸载：

bash

brew uninstall --cask mantra

Windows 卸载

打开"设置" → "应用" → "已安装的应用"
搜索"Mantra"
点击 "..." → "卸载"
按提示完成卸载

或通过控制面板：

打开"控制面板" → "程序" → "程序和功能"
找到 Mantra，右键选择"卸载"

使用包管理器卸载：

ScoopWinget

powershell

scoop uninstall mantra

powershell

winget uninstall Mantra.Mantra

Linux 卸载

AppImage：直接删除 AppImage 文件即可。

bash

rm Mantra-x.x.x.AppImage

DEB 包：

bash

sudo apt remove mantra
# 或完全删除（包括配置）
sudo apt purge mantra

RPM 包：

bash

sudo dnf remove mantra
# 或
sudo yum remove mantra

Flatpak：

bash

flatpak uninstall dev.mantra.Mantra

Snap：

bash

sudo snap remove mantra

删除配置文件（可选）：

bash

rm -rf ~/.config/Mantra
rm -rf ~/.local/share/Mantra

下一步

安装完成后，请阅读快速开始了解如何使用 Mantra。

遇到问题？

如果上述故障排除方法无法解决你的问题，请：

查看常见问题
访问 GitHub Issues 搜索或提交问题
加入社区讨论

安装指南 ​

系统要求概览 ​

macOS 安装 ​

系统要求 ​

方式一：下载 DMG 安装包（推荐） ​

方式二：使用 Homebrew（暂未发布） ​

Windows 安装 ​

系统要求 ​

方式一：下载安装程序（推荐） ​

方式二：使用 Scoop（暂未发布） ​

方式三：使用 Winget（暂未发布） ​

Linux 安装 ​

系统要求 ​

方式一：AppImage（推荐，无需安装） ​

方式二：DEB 包（暂未发布） ​

方式三：RPM 包（暂未发布） ​

方式四：AUR（暂未发布） ​

方式五：Flatpak（暂未发布） ​

方式六：Snap（暂未发布） ​

安装验证 ​

启动应用 ​

版本检查 ​

确认安装成功的标志 ​

故障排除 ​

macOS 常见问题 ​

Windows 常见问题 ​

Linux 常见问题 ​

卸载说明 ​

macOS 卸载 ​

Windows 卸载 ​

Linux 卸载 ​

下一步 ​

安装指南

系统要求概览

macOS 安装

系统要求

方式一：下载 DMG 安装包（推荐）

方式二：使用 Homebrew（暂未发布）

Windows 安装

系统要求

方式一：下载安装程序（推荐）

方式二：使用 Scoop（暂未发布）

方式三：使用 Winget（暂未发布）

Linux 安装

系统要求

方式一：AppImage（推荐，无需安装）

方式二：DEB 包（暂未发布）

方式三：RPM 包（暂未发布）

方式四：AUR（暂未发布）

方式五：Flatpak（暂未发布）

方式六：Snap（暂未发布）

安装验证

启动应用

版本检查

确认安装成功的标志

故障排除

macOS 常见问题

Windows 常见问题

Linux 常见问题

卸载说明

macOS 卸载

Windows 卸载

Linux 卸载

下一步