企业官网建设流程全解析

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

本指南以 docs/development-guide/development-setup.md 为骨架，结合仓库内的 justfile、pyproject.toml、distribute.py 与入口源码，系统讲解 RimSort 的本地开发环境配置、源码运行、Dev 模式数据隔离，以及借助 uv + Nuitka +distribute.py产出 Windows / macOS / Linux 可分发二进制的完整流程。读完本文，你将能够独立完成从克隆仓库到运行、调试、测试、打包的全链路操作，并理解每一步背后的实现原理。

一、技术栈总览：RimSort 是如何构建的

RimSort 是一款面向 RimWorld 的开源跨平台 Mod 管理器（支持 Linux、macOS、Windows），其开发构建链路由以下关键组件组成：

• 编程语言与 GUI：使用 Python 编写，图形界面基于 PySide6（Qt for Python）实现，仓库内app/views/目录下的main_window.py、mods_panel.py、settings_dialog.py等即为其视图层。
• 项目与依赖管理：使用 uv（Python 包与项目管理器）管理解释器、虚拟环境与依赖分组，配置见 pyproject.toml。requires-python = "==3.12.*"严格锁定 Python 3.12。
• 任务运行器：使用 just 将常用开发命令（环境搭建、测试、检查、构建、i18n）封装为统一配方，见仓库根目录的 justfile。
• 编译打包：使用 Nuitka 头部与 rimsort.nuitka-package.config.yml。
• Steam 生态集成：通过两个 git 子模块接入 Steam 相关能力——submodules/steamfiles（解析 Steam 客户端的 acf/appinfo/manifest 信息）与submodules/SteamworksPy（通过 Steamworks API 与本地 Steam 客户端交互，例如在 RimSort 内订阅/取消订阅创意工坊 Mod）。

由于部分依赖（尤其是 SteamworksPy 原生库与 todds 纹理优化器）需要特殊处理，官方提供了自动化构建脚本 distribute.py，这也是下文重点讲解的内容。

二、前置条件：操作系统与工具链

2.1 操作系统

RimSort 支持 Windows、macOS 与 Linux。官方发布构建所基于的 CI 运行环境（也是验证过的基线）为：

需要注意：你的操作系统必须是 PySide6 支持的平台；Linux 发行版上 Ubuntu 是官方基线，其他发行版理论上可用但未经官方验证。

2.2 必备工具

必需软件：

• git —— 拉取仓库与子模块；
• Python 3.12—— 可用 uv 自动安装（uv python install 3.12）；
• uv —— 依赖与虚拟环境管理；
• just —— 开发命令的任务运行器。

代码质量检查工具（just check与 CI 使用）：

• Node.js / npx—— 运行 JSCPD 复制粘贴代码检测（just jscpd）；
• shfmt—— shell 脚本格式化（just shfmt）。

Python 侧的 linter（ruff、mypy、pyright）无需手动安装——uv sync会按 pyproject.toml 的[dependency-groups]自动安装。

2.3 克隆仓库（含子模块）

RimSort 依赖托管在其他仓库的子模块，克隆时必须使用--recurse-submodules：

git clone --recurse-submodules -j8 https://github.com/RimSort/RimSort

-j8让 git 并行拉取子模块以加速。如果克隆时忘记带该参数，或需要更新子模块，执行：

git submodule update --init --recursive

这条命令也是 justfile 中submodules-init配方的实际内容（just dev-setup会自动先执行它）。

三、环境搭建：两条路径殊途同归

3.1 推荐方式：一条命令搞定

在仓库根目录执行：

just dev-setup

该配方（见 justfile 第 199-201 行）依次完成：先执行git submodule update --init --recursive确保子模块就绪，再执行uv sync --locked --dev --group build安装全部运行时、开发与构建依赖（含 ruff、mypy 等 linter），最后运行just i18n-compile将locales/*.ts编译为应用加载所需的locales/*.qm。

3.2 手动方式

如果你希望分步执行：

uv sync --dev # 安装运行时 + 开发依赖（linter、测试工具） uv sync --group build # 额外安装构建依赖（nuitka 等）

uv sync会自动创建/复用.venv虚拟环境。从 pyproject.toml 可以看到依赖分组的设计：[project].dependencies是运行时依赖（PySide6 6.11.2、loguru、aiohttp、networkx、pygit2、steamfiles 等），[dependency-groups].dev是测试与静态检查工具（pytest、pytest-qt、pytest-xvfb、mypy、pyright、ruff），[dependency-groups].build则只包含nuitka==4.2.2。

3.3 安装共享 git hooks

环境就绪后，建议安装共享 git hooks，让just check在每次 commit 前自动运行：

just install-hooks

该配方执行git config core.hooksPath .githooks，将提交前的质量门禁指向仓库内的.githooks目录。

四、从源码运行 RimSort

完成环境搭建后，从项目根目录运行：

uv run python -m app

入口文件为 app/main.py。该入口在初始化 GUI 前做了几件值得了解的事：

• CLI 模式分流：当首个参数为build-db、--help、--version时，直接导入 app/cli/main.py 的cli()并退出，不启动任何 Qt 组件；
• --steamcmd-helper：以runpy方式在当前进程内运行辅助脚本，而不启动完整 GUI（Windows 编译态下还会将标准流映射到活动控制台）；
• 单实例锁：通过 app/utils/single_instance.py 的SingleInstanceLock防止多实例并发运行，锁文件位于应用数据目录下的rimsort.lock；
• 异常兜底：通过sys.excepthook捕获主循环未处理异常并弹出致命错误对话框。

五、Dev 模式：隔离开发数据与生产数据

5.1 为什么需要 Dev 模式

从源码运行 RimSort 时，如果直接使用生产数据目录，开发过程中的调试、误操作可能污染你日常使用的配置。RimSort 为此内置了dev mode：它将所有用户数据（设置、日志、数据库、Mod 列表、主题、备份）重定向到仓库根目录下的dev/子目录。

5.2 激活方式

uv run python -m app --dev

从源码看，--dev标志的处理发生在 app/main.py 第 96-98 行——任何其他初始化之前，将RIMSORT_DEV环境变量置为"1"；随后 app/utils/app_info.py 的_resolve_dev_mode()会解析该变量。

5.3 Dev 模式下发生了什么

• 设置文件保存在dev/data/settings.json；
• 日志写入dev/logs/；
• 数据库（dbs/）、Mod 列表（modlists/）、备份（backups/）均位于dev/data/之下；
• 默认启用 Debug 级日志（见 app/main.py 第 202-207 行：dev 模式强制DEBUG_MODE = True，生产模式则依赖数据目录中是否存在名为DEBUG的文件）；
• 窗口标题显示[DEV]后缀（见 app/views/main_window.py 第 391 行的AppInfo().is_dev_mode分支）。

dev/目录已被写入.gitignore，不会被提交。

5.4 环境变量覆盖

Dev 模式也可以通过环境变量控制，优先级与取值如下（实现见 app/utils/app_info.py 第 36-56 行）：

使用自定义 dev 数据目录：

RIMSORT_DEV_DIR=/tmp/rimsort-test uv run python -m app --dev

或仅通过环境变量（不带--dev）：

RIMSORT_DEV=1 RIMSORT_DEV_DIR=/tmp/rimsort-test uv run python -m app

仓库中 tests/utils/test_app_info_dev_mode.py 对该行为做了完整覆盖，包括合法值解析、非法值告警与RIMSORT_DEV_DIR覆盖逻辑，可作为理解实现细节的参考。

六、SteamworksPy：最需要特殊处理的依赖

RimSort 的实际运行需要三层 Steamworks 相关文件（仓库根目录libs/下已预置）：

1. SteamworksPy Python 模块（子模块内，位于submodules/SteamworksPy/library）；
2. 编译后的 SteamworksPy 原生库——Linux 下为SteamworksPy_<arch>.so，macOS 下为SteamworksPy_<arch>.dylib，Windows 下为SteamworksPy64.dll；
3. Steamworks SDK 的可再分发二进制——libsteam_api.so/libsteam_api.dylib/steam_api64.dll及静态库steam_api.lib等（见 libs/ 目录）。

6.1 使用预编译二进制（推荐）

发布维护者会在仓库与各平台 release 中提供预编译产物。源码环境下，你需要将架构匹配的二进制重命名到位：

• Linux：将SteamworksPy_*.so（*为你的 CPU 架构）复制为SteamworksPy.so；
• macOS：将SteamworksPy_*.dylib复制为SteamworksPy.dylib。

源码模式下这些库的查找路径由 app/utils/app_info.py 的libs_folder属性决定：非编译态返回application_folder / "libs"；Nuitka 编译态则直接使用可执行文件所在目录（macOS 为.app包内Contents/MacOS/）。

6.2 从源码构建 SteamworksPy（可选）

注意：截至文档撰写时，SteamworksPy 模块仅能用Python 11构建，与 RimSort 自身要求的 Python 3.12 不同，你可能需要独立的 Python 环境。

cd SteamworksPy pip install -r requirements.txt

各平台编译要求：

• Linux：需要g++（Ubuntu 开箱即用）；
• macOS：需要 Xcode Command Line Tools，可直接用脚本编译，无需完整 Xcode；
• Windows：需要 Visual Studio 2022 与 Build Tools，安装时选择 "Desktop development with C++" 工作负载（或直接安装 VS Community 2022 标准负载）。

随后可调用distribute.py中的构建函数一键完成 SDK 下载、头文件/库文件拷贝与原生库编译：

python -c "from distribute import build_steamworkspy; build_steamworkspy()"

在 distribute.py 第 79-339 行可以查看完整实现：它会按平台与架构选择编译命令（macOS/Linux 用g++ -std=c++11 -shared -fPIC编译SteamworksPy.cpp并链接-lsteam_api；Windows 用cl配合vcvars64.bat编译SteamworksPy64.dll），下载 Steamworks SDK（默认steamworks_sdk_163.zip，可用--sdk-url/--sdk-zip覆盖），并把产物统一拷贝到仓库根目录libs/。

这是可选步骤——仓库内已提供预编译二进制，无需重复构建。另外请勿在未经维护者同意的情况下提交/PR 这些二进制。

6.3 macOS Gatekeeper 注意事项

macOS 的 Gatekeeper 运行时保护可能导致 RimSort（或依赖库）无法运行。可手动移除隔离属性：

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

七、todds：纹理优化依赖

RimSort 使用 todds 作为纹理优化依赖。正式发布中它被打包进二进制；从源码构建/运行时，你需要手动放置一个 todds 二进制：

• Linux / macOS：./todds/todds
• Windows：.\todds\todds.exe

自动化脚本distribute.py会通过 GitHub API（支持GITHUB_TOKEN环境变量认证）获取最新 release 并按平台下载对应压缩包、解压到todds/目录，且显式补上可执行权限（见 distribute.py 第 361-420 行）。

八、自动化构建：uv run python distribute.py

8.1 一键构建

对大多数场景，最省心的方式是执行仓库提供的自动化脚本：

uv run python distribute.py

它会依次完成：初始化/更新子模块 → （可选）构建或拷贝 SteamworksPy 库 → 获取最新 todds release → 使用 Nuitka 编译应用，最终产出包含全部依赖与子模块的本平台可分发产物。

8.2 完整参数说明

distribute.py使用argparse解析参数（定义见 distribute.py 第 539-613 行），支持按需裁剪流程：

查看完整帮助：

uv run python distribute.py --help

8.3 底层构建原理：freeze_application

distribute.py的freeze_application()（第 423-431 行）揭示了 Nuitka 驱动的关键细节：它先把submodules/SteamworksPy加入PYTHONPATH环境变量，再执行 Nuitka 编译app/包。Nuitka 的实际选项声明在 app/main.py 头部的nuitka-project:注释中，包括：

• 输出文件名RimSort、输出目录build/；
• 启用pyside6插件（覆盖 Qt 插件）；
• --include-package=steamworks、--include-data-file=steam_appid.txt（Steamworks 运行需要）；
• 内嵌themes/default-icons/AppIcon_alt.ico（Windows 图标）与AppIcon_a.icns（macOS）；
• macOS 使用--mode=app生成.app包，其余平台使用--mode=standalone；
• 若存在version.xml则内嵌版本信息（AppInfo启动时读取它显示版本号）；
• 附带--python-flag=no_asserts,no_docstrings等优化。

构建完成后，macOS 还会执行两个后处理步骤（见 distribute.py 第 443-516 行）：post_build_fixup_macos_steamworks确保.app包内存在通用的SteamworksPy.dylib（按宿主 CPU 挑选合适的架构变体拷贝）；post_build_optimize_macos_bundle调用 packaging/optimize_macos_bundle.py 瘦身 fat binaries 以减小体积。

如果你需要本地快速迭代而直接驱动 Nuitka，务必记得按上述方式设置PYTHONPATH并保持与distribute.py一致的选项；真实构建仍推荐优先使用distribute.py。

九、打包与分发：just build 与平台产物

9.1 通过 just 构建

justfile 的build配方（第 228-234 行）在调用distribute.py前会先执行子模块初始化、全量质量检查（check）与 i18n 编译，保证产物干净：

just build # 标准构建 just build-version 1.2.3.4 # 指定版本号构建

Linux 下还可将既有 Nuitka 输出进一步打包为 AppImage：

just build-appimage VERSION='1.0.0'

Windows 下官方另有 packaging/msi/RimSort.wixproj 与 packaging/msi/build_msi.ps1 生成 MSI 安装包，Linux 的桌面集成文件位于 packaging/linux/。

9.2 常用开发配方速查

以下是 justfile 中最常用的配方：

9.3 测试与代码质量

RimSort 的测试位于 tests/ 目录，覆盖排序算法（tests/sort/）、元数据（tests/models/metadata/）、Steam 相关工具（tests/utils/steam/）、视图与窗口（tests/views/、tests/windows/）等模块。运行：

just test

质量检查体系（just check/ CI）包括：ruff lint 与格式、mypy 与 pyright 类型检查、JSCPD 复制粘贴检测、shfmt 脚本格式、markdownlint、gitleaks 密钥扫描、checkov 配置扫描等，配置均集中在 pyproject.toml 与仓库根目录的各类配置文件（如.jscpd.json、.markdownlint.json）。

十、常见问题与排错要点

• 子模块缺失：克隆时未带--recurse-submodules，运行报模块导入错误——执行git submodule update --init --recursive或just dev-setup；
• SteamworksPy 导入失败：确认libs/下存在重命名后的通用库（SteamworksPy.so/SteamworksPy.dylib/SteamworksPy64.dll），且与你的 CPU 架构匹配；
• macOS 无法启动/依赖库无法加载：检查是否被 Gatekeeper 隔离，使用xattr -d com.apple.quarantine移除隔离属性；
• 从源码运行污染生产数据：使用uv run python -m app --dev（或RIMSORT_DEV=1）启用数据隔离；
• 翻译未生效/缺失.qm：执行just i18n-compile重新编译 locales/ 下的翻译文件；
• Windows 多进程问题：Nuitka 编译态下程序会自动调用multiprocessing.freeze_support()并将启动方式切换为spawn（见 app/main.py 第 221-228 行），无需手动处理。

十一、总结：完整的开发到发布工作流

将上述内容串起来，RimSort 的典型开发发布流程为：

1. git clone --recurse-submodules -j8克隆仓库与子模块；
2. just dev-setup一键完成依赖与翻译编译；
3. just install-hooks安装提交前质量门禁；
4. uv run python -m app --dev在隔离环境中运行、调试；
5. just check && just test通过全部质量检查与测试；
6. uv run python distribute.py（或just build）产出本平台可分发二进制；
7. 跨平台发布则依赖 GitHub Actions 流水线在文档第二节所列的 CI 运行环境上分别构建 Linux / macOS（x86_64 与 arm）/ Windows 产物。

无论是本地开发还是为 RimSort 贡献代码，本文覆盖的每一环节都有仓库内的源码、配置与测试可查证：环境定义见 pyproject.toml，命令封装见 justfile，构建编排见 distribute.py，运行时入口见 app/main.py，路径与 dev 模式逻辑见 app/utils/app_info.py。

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