企业官网建设流程全解析

• 桌面应用
• 游戏开发
• CLI

RimSort 是一款面向《环世界》(RimWorld) 的开源跨平台 Mod 管理器，官方为 Windows、macOS、Linux 提供预编译的二进制发行版。本文以官方安装文档 docs/user-guide/downloading-and-installing.md 为主体，结合仓库源码（如 app/utils/app_info.py、app/main.py、app/utils/update_utils.py）深入讲解发行版类型的选择、三大平台的安装启动步骤、Linux 下 RimWorld 与 RimSort 的路径布局、Qt 依赖补齐以及常见故障排查，读完即可独立完成任一平台的安装与验证。

发行版类型：Stable 与 Edge

RimSort 官方发布两种类型的发行版（Release）：

选择发行版时，需要同时考虑三个因素：操作系统（Windows / macOS / Linux）、CPU 架构（x86_64 / ARM64）以及自身需求（是否需要 Steamworks 深度集成、纹理压缩等附加能力）。各平台的启动方式有所差异，详见下文。

⚠️重要提醒：绝大多数用户应当使用预编译发行版，而不是从仓库页面通过Code > Download ZIP下载源码。ZIP 下载的是未编译的源代码，无法直接运行；只有在计划参与贡献、自行构建 RimSort 或通过 Python 解释器运行源码时，才需要获取源码（源码运行方式见 docs/development-guide/development-setup.md）。

Windows 安装

Windows 平台提供Windows x86-64发行版，安装步骤非常简洁：

1. 下载并解压Windows x86-64发行版压缩包；
2. 进入解压目录，运行可执行文件RimSort.exe。

关于杀毒软件误报的说明

Windows 上运行RimSort.exe时，有可能被 Windows Defender 等杀毒软件误报并直接删除。这是使用 Nuitka 将 Python 程序编译为可分发的可执行文件、且未进行代码签名所产生的副作用——代码签名证书价格昂贵且需要持续续费，项目无力承担。RimSort 本身是安全的，用户可以放心地在杀毒软件中为该程序添加白名单。如果不放心，也可以将可执行文件提交到 VirusTotal 等在线多引擎扫描服务，综合多家杀毒引擎的意见后再自行判断。

从源码结构看，该可执行文件由distribute.py驱动 Nuitka 编译app/包生成（见 docs/development-guide/development-setup.md 的 "Packaging RimSort" 一节），因此单文件可执行、体积大、启动稍慢都属于 Nuitka 冻结（freeze）后的正常特征，并不代表程序有问题。

macOS 安装

macOS 用户需要根据 CPU 架构选择对应发行版：

• ARM64：Apple Silicon（M1/M2 及更新机型）；
• x86_64：Intel 芯片的 Mac。

安装步骤：

1. 下载并解压与 CPU 架构匹配的 Darwin/macOS 发行版；
2. 使用xattr命令规避 Gatekeeper 并放行RimSort.app与libsteam_api.dylib；
3. 打开应用包RimSort.app。

Gatekeeper 放行（xattr）

Apple 的系统运行时保护机制 Gatekeeper 可能会阻止 RimSort 启动，甚至提示应用"已损坏"。可以通过xattr命令手动移除隔离属性来放行：

xattr -d com.apple.quarantine /path/to/RimSort.app xattr -d com.apple.quarantine /path/to/libsteam_api.dylib

把/path/to/替换为文件/文件夹的实际路径，例如：

xattr -d com.apple.quarantine /Users/John/Downloads/RimSort.app

在 docs/development-guide/development-setup.md 的 "Manually building" 一节中，同样的xattr操作被推荐给源码运行/自建版本的用户，说明这是 macOS 上无论发行版还是源码方式都通用的必经步骤。

Apple Silicon 上的额外注意

• 如果出于某种原因在 Apple Silicon 上运行x86_64构建（即通过 Rosetta 2 转译），不要启用 watchdog 功能；
• todds 纹理压缩工具目前（截至 2023 年 5 月）不支持 Apple Silicon（M1/M2 ARM64 CPU）。

watchdog 是 RimSort 内置的文件监视功能（源码位于 app/utils/watchdog.py），默认开启（app/models/settings.py 中watchdog_toggle默认为True），用于监听appworkshop_294100.acf等 Steam 文件变化以自动刷新 Mod 状态。在 Rosetta 转译环境下它可能引发异常，故官方建议关闭。

Linux 安装

Linux 平台提供多种安装形态，按推荐程度依次为：AppImage（推荐）、Ubuntu Tarball、源码运行（最后手段）。

AppImage（推荐）

AppImage 是最简单的运行方式：它打包了全部依赖，无需安装任何东西即可在绝大多数发行版上运行。

1. 从发布页面下载.AppImage文件；
2. 赋予可执行权限并运行：

chmod +x RimSort-*.AppImage ./RimSort-*.AppImage

FUSE 依赖：AppImage 运行依赖 FUSE2。大多数发行版自带，但如果遇到 FUSE 相关报错，可以通过包管理器安装fuse2/libfuse2，或改用--appimage-extract-and-run参数绕过 FUSE 直接解压运行：

./RimSort-*.AppImage --appimage-extract-and-run

桌面集成：如需自动加入桌面应用菜单并方便更新，可以考虑 AppImageLauncher 这类工具，它会将 AppImage 注册进桌面环境，使其像普通已安装应用一样出现在应用菜单中。

自更新机制：以 AppImage 方式运行时，RimSort 内置的更新器会原地替换AppImage 文件（旧版本先备份为.bak，下次启动时自动清理）。这一行为在源码中有明确实现：

• app/utils/update_utils.py 的_prepare_appimage_update()会将新版本写入运行中 AppImage 同目录下的.new文件，随后在更新流程中通过.bak重命名作为备份（跳过 ZIP 备份逻辑）；
• app/utils/app_info.py 的_cleanup_appimage_backup()在应用初始化时自动清理上次更新遗留的.bak文件；
• 由于 AppImage 的application_folder是只读的 FUSE 挂载点，更新器会改为在.AppImage文件自身所在的目录进行替换（对应is_appimage判断，见 app/utils/app_info.py 中基于$APPIMAGE环境变量的检测逻辑）。

由此可以推断：AppImage 必须放在用户可写的目录中，否则自更新会失败（详见下文"故障排查"）。

Ubuntu Tarball

预编译的 Tarball 发行版基于 Ubuntu 22.04 与 24.04 构建，也可能在其他基于 Debian 的发行版或 glibc 版本兼容的发行版上运行，但不保证兼容性。

1. 下载并解压与你 Ubuntu 版本匹配的.tar.gz（或.zip）发行版；
2. 运行可执行文件：

./RimSort

⚠️ 如果所有预编译发行版在你的发行版上都无法运行，可以自行从源码构建或通过 Python 解释器运行，具体步骤见 docs/development-guide/development-setup.md。

Qt 依赖

RimSort 使用 Qt（PySide6）构建 GUI。使用 Tarball 发行版（而非 AppImage）时，系统可能缺少 Qt 共享库，最常见的缺失库是libxcb-cursor。

Debian / Ubuntu：

sudo apt install libxcb-cursor0

如果还有其他缺失库，可用apt-file定位所属软件包：

sudo apt install apt-file apt-file update apt-file search libxcb-whatever.so

Fedora / RHEL：

sudo dnf install xcb-util-cursor

使用dnf provides查找其他缺失库对应的软件包：

dnf provides '*/libxcb-whatever.so*'

Arch / Manjaro：

sudo pacman -S xcb-util-cursor

使用pkgfile搜索缺失库：

pkgfile libxcb-whatever.so

提示：文档中以libxcb-whatever.so作为占位符，实际排查时应替换为报错信息中出现的真实库名。

Linux 上的 RimWorld 路径

RimSort 需要知道 RimWorld 的安装位置以及配置存放位置，这两类路径会因 Steam 与 RimWorld 的安装方式不同而变化。

⚠️官方强烈推荐使用发行版软件源安装的原生 Steam（Native Steam）+ RimWorld 原生 Linux 版本，这是兼容性最好的组合方式。

Native Steam（推荐）

如果 Steam 库安装在其他磁盘/分区上，游戏安装目录与 Workshop 路径应改为该库对应的steamapps/目录。

294100是 RimWorld 的 Steam App ID，在 app/utils/constants.py 中以常量RIMWORLD_STEAM_APP_ID = "294100"定义，RimSort 依据它定位 Workshop 内容目录。

Flatpak Steam

通过 Flatpak 安装的 Steam 会把所有路径沙箱化到~/.var/app/com.valvesoftware.Steam/下：

⚠️Snap 版 Steam 不受支持且不推荐：Snap 包存在已知的游戏兼容性问题，且未获得 Valve 官方支持，请改用原生.deb包或 Flatpak 版本。

Proton（通过 Steam Play 运行 Windows 版 RimWorld）

如果通过 Proton 运行 Windows 版 RimWorld 而非原生 Linux 版，配置文件夹位于 Proton 的虚拟 Windows 文件系统中：

游戏安装目录与 Workshop Mod 路径与 Native Steam 相同。若使用 Flatpak Steam + Proton，需要在 compatdata 路径前加上~/.var/app/com.valvesoftware.Steam/前缀。

通过 Proton 运行时，RimWorld 可执行文件是RimWorldWin64.exe（或RimWorldWin.exe）而不是RimWorldLinux。RimSort 会自动检测两者，但手动设置路径时需要留意。

原生 Linux 版 RimWorld 优于 Proton：路径更简单，与 RimSort 各功能的兼容性更好。

RimSort 自身的数据位置

RimSort 使用platformdirs库按照各平台惯例存放自身数据。在 Linux 上：

源码层面，这些路径由 app/utils/app_info.py 的AppInfo单例类解析：非开发模式下通过PlatformDirs(appname="RimSort", appauthor=False)的user_data_dir与user_log_dir得到上述目录，并派生dbs（数据库）、modlists（Mod 列表）、themes（主题）、backups（备份）等子目录。若以--dev参数运行源码（开发模式），则所有数据会重定向到仓库根目录下的dev/子目录，避免污染生产数据。

开启调试日志

在应用数据目录中创建一个名为DEBUG的空文件即可启用调试级日志：

touch ~/.local/share/RimSort/DEBUG

这个机制在源码中有直接对应：见 app/main.py —— 非开发模式下，程序检查AppInfo().app_storage_folder / "DEBUG"是否存在且为文件，若存在则将日志级别设为 DEBUG（setup_logging中file_level = "DEBUG" if debug else "INFO"，见 app/utils/log_setup.py）。

Wayland 与 X11

RimSort 基于 PySide6（Qt6），原生支持 Wayland，大多数情况下无需额外配置即可正常运行。

如果在 Wayland 下遇到渲染异常或崩溃，可以通过 XWayland 强制使用 X11 模式：

QT_QPA_PLATFORM=xcb ./RimSort

AppImage 版本同理：

QT_QPA_PLATFORM=xcb ./RimSort-*.AppImage

故障排查

glibc 版本不匹配：Tarball 预编译发行版链接的是 Ubuntu 的 glibc，如果你的发行版 glibc 版本较旧，会报出类似GLIBC_2.xx not found的错误。此时请改用 AppImage，或从源码构建。

AppImage 无法启动（FUSE 错误）：从包管理器安装fuse2或libfuse2；或者使用--appimage-extract-and-run参数绕过 FUSE 要求。

AppImage 自更新失败：AppImage 必须位于用户可写目录。如果放在需要 root 权限的位置（如/opt/），请将其移动到主目录，或手动更新。

Steam 集成不工作：启动 RimSort 前请确保 Steam 已在运行——Steamworks API 需要活跃的 Steam 客户端连接（源码中通过SteamworksPy模块与本地 Steam 客户端交互，对应 libs/ 目录下的SteamworksPy*.so/.dylib/.dll预编译库）。若使用 Flatpak Steam，在沙箱外运行的 RimSort 可能无法与之通信，官方推荐使用原生 Steam。

Mod 路径未检测到：如果 RimSort 找不到 Mod 或配置，请确认你使用的 Steam 安装方式（原生、Flatpak 或 Snap），并在 RimSort 设置中手动指定路径，路径表参见上文 RimWorld 路径章节。

最后的办法——从源码运行：如果所有预编译发行版在你的环境都无法运行，可以直接通过 Python 解释器运行源码，完整步骤参见 docs/development-guide/development-setup.md（概览：克隆仓库（含子模块）→uv sync安装依赖 →uv run python -m app启动）。

小结

安装 RimSort 的核心要点可以归纳为四条：一是优先选择与平台、CPU 架构匹配的Stable预编译发行版；二是按平台处理系统级障碍（Windows 杀毒误报、macOS Gatekeeper 放行、Linux Qt 依赖与 FUSE）；三是在 Linux 上根据 Steam 安装方式（原生 / Flatpak / Proton）正确理解 RimWorld 与 RimSort 的路径布局；四是遇到问题时善用DEBUG文件启用调试日志、查看~/.local/state/RimSort/log/RimSort.log定位原因。对希望深度定制或排查疑难问题的用户，docs/development-guide/development-setup.md 提供了从源码构建与运行的完整指引。

• 桌面应用
• 游戏开发
• CLI