开发环境

获取源码

安装 Git、Rustup 和 just。 使用操作系统的原生构建工具。 macOS 需要 Xcode Command Line Tools。 Windows 需要 Visual Studio C++ 构建工具。

如果没有仓库写权限，先创建 GitHub fork。 在下方克隆命令中使用 fork 的 URL。

1. 克隆仓库。
2. 打开仓库根目录。

git clone https://github.com/EdwinZhanCN/LumilioCL.git
cd LumilioCL

为修改创建分支。 前缀见分支与合并：

git switch -c fix/<change-name>

安装 rust-toolchain.toml 指定的工具链：

rustup toolchain install

开发工具链由仓库指定。 不要自行替换 Rust 版本。

准备 Linux 库

Linux CI 使用以下软件包。

sudo apt-get update
sudo apt-get install -y --no-install-recommends \
  build-essential clang cmake pkg-config \
  libssl-dev libzstd-dev libfontconfig-dev libfreetype-dev \
  libvulkan-dev libwayland-dev libxkbcommon-dev libxkbcommon-x11-dev \
  libx11-dev libx11-xcb-dev libxcb1-dev

运行启动器还需要桌面会话和图形驱动。 当前软件包列表见 CI workflow。

运行启动器

在仓库根目录运行：

cargo run -p lumilio-app

手动测试使用临时数据目录。 启动应用前，把 LUMILIO_HOME 设为该目录。 破坏性测试不要使用重要游戏数据。

配置 CurseForge API 密钥

CurseForge 内容源在构建时读取环境变量 CF_API_KEY。 没有密钥时，这个来源默认关闭，其他功能照常使用。 发布构建从仓库的 Secret 注入密钥。

本地开发时，把密钥放进用户级的 ~/.cargo/config.toml：

[env]
CF_API_KEY = '你的密钥'

使用单引号，密钥里的 $ 才会原样保留。 不要把密钥写进仓库里的 .cargo/config.toml，这个文件受 Git 跟踪。 修改密钥后，Cargo 会重新编译用到它的 crate。

准备网站

安装 Node.js 22.12.0 或更新版本。 pnpm 版本使用 web/package.json 的 packageManager 字段。 在 web/ 中运行 pnpm 命令。

cd web
pnpm install --frozen-lockfile
pnpm dev

打开 Astro 输出的本地 URL。 中文文档位于 /docs/，英文文档位于 /en/docs/。

选择检查

以下 recipe 在仓库根目录运行。

修改范围	迭代检查	交接前检查
Rust 代码	just test-pkg <crate> [filter]	just check
forks/ 里的 fork	just forks	just check 和 just forks
文档或 harness	修改计划后运行 just plans	just docs
网站或公开文档	just web	just web；修改计划时还需 just docs

just check 依次执行构建、测试、Clippy 和格式检查。 just forks 运行启动器所用 fork 自己的测试。CI 运行 just ci，即先 just check 再 just forks。 just web 执行依赖安装、Astro 检查、网站测试和站点构建。 命令成功结束前，不得声称检查已通过。