Mantra 文档

简体中文

English

简体中文

English

主题

安装指南 ​

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

系统要求概览 ​

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

操作系统最低版本架构磁盘空间
macOS12.0 (Monterey)Intel / Apple Silicon至少 500MB
Windows10 (版本 1903+)64 位至少 500MB
LinuxUbuntu 22.04+ / Fedora 36+ / Debian 12+64 位 (x86_64)至少 500MB

关于磁盘空间

安装包本身约 16–96MB（取决于格式），应用安装后约占 70–150MB。预留 500MB 是为了容纳会话缓存和代码快照数据。

安装包文件名规则

所有安装包统一命名为 Mantra_{版本号}_{平台}-{架构}.{格式}，例如 Mantra_0.12.7_macos-arm64.dmg。

下载页中带 .sig、.app.tar.gz 后缀的文件是自动更新专用产物，手动安装时无需下载。

macOS 安装 ​

系统要求 ​

  • 操作系统: macOS 12.0 (Monterey) 或更高版本
  • 处理器: Intel 或 Apple Silicon (M1/M2/M3/M4)，两种架构均为原生构建
  • 磁盘空间: 至少 500MB 可用空间
  • 权限: 需要管理员权限安装

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

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

  1. 下载安装包

    访问 Mantra 官网下载页面，选择 macOS 版本下载 .dmg 文件。

    选择正确的版本

    • Apple Silicon (M1/M2/M3/M4): 下载 Mantra_{版本号}_macos-arm64.dmg
    • Intel Mac: 下载 Mantra_{版本号}_macos-x64.dmg

    不确定你的 Mac 类型？点击左上角 → "关于本机"，查看"芯片"或"处理器"信息。

    💡 下载页会自动识别你的芯片类型并推荐对应版本。

  2. 打开安装包

    双击下载的 .dmg 文件，将出现安装窗口。

  3. 安装应用

    将 Mantra 图标拖拽到 Applications（应用程序）文件夹。

  4. 首次启动

    打开"应用程序"文件夹，找到 Mantra 并双击启动。

    应用已通过 Apple 公证

    Mantra 已通过 Apple Developer ID 签名并完成公证（Notarization），首次启动直接双击打开即可，不会出现"无法验证开发者"等安全警告。

方式二：使用 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（版本 1903+）或更高版本
  • 架构: 64 位系统 (x64)
  • 磁盘空间: 至少 500MB 可用空间
  • 权限: 需要管理员权限安装

如何确认系统架构

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

Windows 7/8 不支持

由于技术限制，Mantra 不支持 Windows 7 和 Windows 8/8.1。

Windows 提供两种安装包，功能完全一致，按需选择：

格式文件名体积适用场景
EXE (NSIS)Mantra_{版本号}_windows-x64-setup.exe~16MB个人用户，安装向导支持中英文切换
MSI (WiX)Mantra_{版本号}_windows-x64.msi~21MB企业批量部署，支持组策略和静默安装

方式一：EXE 安装程序（推荐个人用户） ​

  1. 下载安装程序

    访问 Mantra 官网下载页面，下载 Mantra_{版本号}_windows-x64-setup.exe。

  2. 运行安装程序

    双击下载的 .exe 文件，启动安装向导。安装向导支持简体中文和英文，启动时可选择语言。

    Windows SmartScreen 提示

    首次运行时，Windows SmartScreen 可能显示"Windows 已保护你的电脑"提示。

    解决方法：

    1. 点击"更多信息"
    2. 点击"仍要运行"

    这是因为应用尚未获得 Windows 签名认证，但下载自官网是安全的。

  3. 完成安装

    按照安装向导提示，选择安装位置并完成安装。

  4. 启动 Mantra

    安装完成后，可以通过以下方式启动：

    • 从开始菜单搜索"Mantra"
    • 双击桌面快捷方式（如已创建）

方式二：MSI 安装包（推荐企业部署） ​

MSI 格式适合需要通过组策略（GPO）或 SCCM 等工具批量部署的场景。

  1. 下载安装包

    访问 Mantra 官网下载页面，下载 Mantra_{版本号}_windows-x64.msi。

  2. 交互式安装

    双击 .msi 文件，按提示完成安装。

  3. 静默安装（批量部署）

    在管理员权限的命令提示符或 PowerShell 中执行：

    powershell
    # 静默安装，无界面
msiexec /i Mantra_0.12.7_windows-x64.msi /quiet /norestart

# 静默安装并指定安装目录
msiexec /i Mantra_0.12.7_windows-x64.msi /quiet INSTALLDIR="D:\Apps\Mantra"

# 静默安装并生成日志（便于排查部署失败）
msiexec /i Mantra_0.12.7_windows-x64.msi /quiet /l*v install.log

    静默卸载

    powershell
    msiexec /x Mantra_0.12.7_windows-x64.msi /quiet

    MSI 安装向导语言

    MSI 安装向导目前仅提供英文界面，但应用本身完整支持中英文，首次启动后可在设置中切换。如需中文安装向导，请使用 EXE 版本。

方式三：使用 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 22.04+, Debian 12+, Fedora 36+, Arch Linux, 或其他同等新度的主流发行版
  • 架构: 64 位 (x86_64)
  • 磁盘空间: 至少 500MB 可用空间
  • 依赖: WebKit2GTK 4.1、GTK 3、libayatana-appindicator（AppImage 已内置大部分依赖）

关于发行版下限

Mantra 基于 WebKit2GTK 4.1 构建，官方构建环境为 Ubuntu 22.04。更旧的发行版（如 Ubuntu 20.04、Debian 11）只提供 WebKit2GTK 4.0，无法运行。这类系统请使用 AppImage 格式，或升级发行版。

Linux 提供三种安装包，功能完全一致：

格式文件名体积适用场景
DEBMantra_{版本号}_linux-x64.deb~26MBDebian / Ubuntu / Mint，集成系统菜单
RPMMantra_{版本号}_linux-x64.rpm~26MBFedora / RHEL / openSUSE，集成系统菜单
AppImageMantra_{版本号}_linux-x64.AppImage~96MB任意发行版，免安装便携运行

该选哪个？

如果你用的是 Debian/Ubuntu 或 Fedora 系发行版，优先选 DEB 或 RPM —— 体积只有 AppImage 的四分之一，并且会自动注册到应用菜单。AppImage 体积较大是因为它把运行时依赖全部打包在内，换来的是跨发行版的通用性。

方式一：DEB 包（Debian / Ubuntu 推荐） ​

适用于 Debian 12+、Ubuntu 22.04+、Linux Mint 21+ 等基于 Debian 的发行版。

  1. 下载 DEB 包

    访问 Mantra 官网下载页面 或 GitHub Releases，下载 Mantra_{版本号}_linux-x64.deb。

  2. 安装

    bash
    # 使用 apt 安装（推荐，会自动处理依赖）
sudo apt install ./Mantra_0.12.7_linux-x64.deb

# 或使用 dpkg
sudo dpkg -i Mantra_0.12.7_linux-x64.deb
# 若提示缺少依赖，运行
sudo apt-get install -f

    推荐用 apt 而非 dpkg

    apt install ./xxx.deb 会自动解析并安装缺失依赖，dpkg -i 不会，需要事后手动修复。

  3. 启动应用

    安装后可从应用菜单搜索 "Mantra" 启动，或在终端运行：

    bash
    mantra

方式二：RPM 包（Fedora / RHEL 推荐） ​

适用于 Fedora 36+、RHEL 9+、openSUSE 等使用 RPM 的发行版。

  1. 下载 RPM 包

    访问 Mantra 官网下载页面 或 GitHub Releases，下载 Mantra_{版本号}_linux-x64.rpm。

  2. 安装

    bash
    # Fedora / RHEL 9+
sudo dnf install ./Mantra_0.12.7_linux-x64.rpm

# openSUSE
sudo zypper install ./Mantra_0.12.7_linux-x64.rpm

  3. 启动应用

    安装后可从应用菜单搜索 "Mantra" 启动，或在终端运行：

    bash
    mantra

方式三：AppImage（免安装，通用） ​

AppImage 是一种便携式应用格式，无需安装即可运行，适用于所有 Linux 发行版 —— 包括那些 WebKit2GTK 版本偏旧、无法安装 DEB/RPM 的系统。

  1. 下载 AppImage

    访问 Mantra 官网下载页面，下载 Mantra_{版本号}_linux-x64.AppImage。

  2. 添加执行权限

    bash
    chmod +x Mantra_0.12.7_linux-x64.AppImage

  3. 运行应用

    bash
    ./Mantra_0.12.7_linux-x64.AppImage

    集成到应用菜单

    AppImage 默认不会出现在应用菜单里。首次运行时，Mantra 会询问是否集成到桌面环境（v0.12.2+ 已修复图标和名称显示问题）。你也可以使用 AppImageLauncher 统一管理。

AppImage 的优势

  • 无需 root 权限
  • 不影响系统其他软件
  • 便于尝试不同版本
  • 可放在任意位置运行
  • 兼容 DEB/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，此处会显示版本号，并可手动检查更新。

Mantra 没有命令行工具

Mantra 是纯图形界面应用，不提供 mantra --version 之类的命令行参数。Linux 上通过 DEB/RPM 安装后虽然可以在终端输入 mantra 启动应用，但它只会打开图形窗口，不接受命令行参数。

确认安装成功的标志 ​

  • [x] 应用能够正常启动
  • [x] 欢迎界面正确显示
  • [x] 系统托盘 (v0.7.0+)：主窗口关闭后，托盘图标应继续显示，表示应用在后台运行
  • [x] 可以创建新项目或打开现有项目

自动更新 ​

从 v0.8.0 版本开始，Mantra 内置了自动更新系统：

  • 自动检查：应用启动时会自动检查新版本。
  • 后台下载：新版本将在后台静默下载，不会打断你的工作。
  • 一键重启：下载完成后，设置按钮会出现更新提示，点击即可重启并安装新版本。

你也可以在 设置 -> 常规 -> 关于 Mantra 中手动检查更新。

故障排除 ​

macOS 常见问题 ​

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

原因：macOS Gatekeeper 安全机制会阻止未经公证的应用。当前版本已通过 Apple 公证，正常情况下不会出现此提示；如果你运行的是旧版本，或安装包来自非官方渠道，则可能遇到。

解决方案：

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

或者在系统设置中：

  1. 打开"系统设置" → "隐私与安全性"（macOS 12 为"系统偏好设置" → "安全性与隐私"）
  2. 点击"仍要打开"

建议从官网下载最新版本，即可避免此提示。

"Mantra" 已损坏，无法打开

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

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

bash
xattr -cr /Applications/mantra.app

注意应用名是小写

安装到 Applications 后，应用 bundle 的实际名称是 mantra.app（小写）。如果上面的命令提示路径不存在，可以先确认实际名称：

bash
ls -d /Applications/*antra*.app

:::

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

原因：可能下载了 Intel 版本而不是 ARM 版本，此时应用会通过 Rosetta 2 转译运行，性能明显下降。

解决方案： 确保下载文件名包含 macos-arm64 的版本（而非 macos-x64）。

提示需要 macOS 12.0 或更高版本

原因：Mantra 最低支持 macOS 12.0 (Monterey)。

解决方案： 点击左上角 → "关于本机" 查看系统版本。若低于 12.0，需先升级 macOS。

Windows 常见问题 ​

Windows SmartScreen 阻止运行

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

解决方案：

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

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

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

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

解决方案：

  1. 确认系统是 64 位（设置 → 系统 → 关于）
  2. 重新下载正确版本的安装程序（文件名含 windows-x64）
MSI 静默安装失败，没有任何提示

原因：/quiet 模式下所有错误都不显示，且需要管理员权限。

解决方案：

  1. 确认以管理员身份运行命令提示符或 PowerShell
  2. 加上日志参数重新执行，然后查看日志定位原因：
    powershell
    msiexec /i Mantra_0.12.7_windows-x64.msi /quiet /l*v install.log
  3. 在 install.log 中搜索 Return value 3，其上方几行通常是真正的失败原因
缺少 VCRUNTIME140.dll 或其他 DLL 文件

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

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

Linux 常见问题 ​

AppImage 无法运行

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

解决方案：

bash
# 添加执行权限
chmod +x Mantra_0.12.7_linux-x64.AppImage

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

# Fedora
sudo dnf install fuse fuse-libs
DEB/RPM 包安装后无法启动

原因：缺少依赖，最常见的是 WebKit2GTK 版本不匹配。

解决方案：

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

# 检查 WebKit2GTK 4.1 是否存在（Mantra 依赖此版本）
apt list --installed | grep webkit2gtk    # Debian/Ubuntu
dnf list installed | grep webkit2gtk      # Fedora

# 从终端启动以查看错误输出
mantra

如果提示找不到 libwebkit2gtk-4.1.so，说明你的发行版版本过低（仅提供 4.0）。请改用 AppImage 格式，或升级到 Ubuntu 22.04+ / Debian 12+ / Fedora 36+。

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

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

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

bash
# 方法 1：强制缩放
GDK_SCALE=2 ./Mantra_0.12.7_linux-x64.AppImage

# 方法 2：禁用自动 DPI 缩放
GDK_DPI_SCALE=0.5 ./Mantra_0.12.7_linux-x64.AppImage

通过 DEB/RPM 安装的版本同理，把环境变量加在 mantra 命令前即可。

卸载说明 ​

macOS 卸载 ​

手动卸载：

  1. 退出 Mantra 应用
  2. 打开 Finder → 应用程序
  3. 将 Mantra 拖到废纸篓
  4. （可选）删除配置文件：
    bash
    rm -rf ~/Library/Application\ Support/com.gonewx.mantra
rm -rf ~/Library/Preferences/com.gonewx.mantra.plist

使用 Homebrew 卸载（Homebrew 安装方式暂未发布）：

bash
brew uninstall --cask mantra

Windows 卸载 ​

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

或通过控制面板：

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

使用包管理器卸载：

powershell
msiexec /x Mantra_0.12.7_windows-x64.msi /quiet
powershell
scoop uninstall mantra
powershell
winget uninstall Mantra.Mantra

Linux 卸载 ​

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

bash
rm Mantra_0.12.7_linux-x64.AppImage

如果之前做过桌面集成，还需删除生成的快捷方式：

bash
rm -f ~/.local/share/applications/*mantra*.desktop

DEB 包：

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

RPM 包：

bash
sudo dnf remove mantra
# openSUSE
sudo zypper remove mantra

Flatpak：

bash
flatpak uninstall dev.mantra.Mantra

Snap：

bash
sudo snap remove mantra

删除配置文件（可选）：

bash
rm -rf ~/.config/com.gonewx.mantra
rm -rf ~/.local/share/com.gonewx.mantra

下一步 ​

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

遇到问题？

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