企业官网建设流程全解析

• 桌面应用
• CLI

Ludusavi（PC 游戏存档备份工具）将配置、日志与数据清单统一存放在一个"应用文件夹"中，本文基于官方帮助文档 application-folder.md，结合仓库源码，系统讲解该目录在 Windows / Linux / macOS 各平台的确切位置、便携模式（portable mode）的判定机制与适用场景、目录内关键文件（config.yaml、manifest.yaml等）的职责，并给出通过命令行定位与导出配置的实操方法。读完本文，你将能精准找到 Ludusavi 的配置文件、理解ludusavi.portable标志文件的工作原理，并在多机迁移、U 盘随身携带等场景下正确规划数据存放。

一、Ludusavi 应用文件夹是什么

Ludusavi 是一个"绿色"的 PC 游戏存档备份工具，它的程序本体可以放在任意位置直接运行（安装指南 明确说明：下载的可执行文件是便携的，放哪里都行），但它的配置、日志、数据清单并不会跟随可执行文件，而是集中写入一个统一的"应用文件夹"（application folder）。

官方文档给出各平台默认位置如下：

• Windows的%APPDATA%通常展开为C:\Users\<用户名>\AppData\Roaming，因此实际路径一般为C:\Users\<用户名>\AppData\Roaming\ludusavi。
• Linux下若已设置XDG_CONFIG_HOME环境变量则优先使用该变量的值，否则回落到~/.config。
• Flatpak沙箱会把配置文件重定向到~/.var/app/com.github.mtkennerly.ludusavi/config/ludusavi，其对应的桌面与元数据文件见仓库 assets/flatpak/ 目录（com.github.mtkennerly.ludusavi.desktop与com.github.mtkennerly.ludusavi.metainfo.xml）。

这些默认位置均由操作系统层面的"配置目录"约定推导而来。在源码中，目录定位统一收敛到 src/prelude.rs 的常量APP_DIR_NAME = "ludusavi"，即"应用文件夹名 = 配置目录 +ludusavi子目录"。

二、便携模式：把配置放到可执行文件旁边

默认情况下配置写入系统标准配置目录，但在某些场景下你可能希望Ludusavi 把配置存放在与可执行文件相同的目录——官方文档给出的典型场景是"从 U 盘在多台电脑上运行 Ludusavi"，这样配置可以随 U 盘随身携带，换电脑即插即用。

启用方式非常简单：在包含 Ludusavi 可执行文件的目录中，创建一个名为ludusavi.portable的文件（内容可以为空，仅作为标志存在）。之后 Ludusavi 就会把应用文件夹解析为可执行文件所在目录本身，config.yaml、manifest.yaml、日志等都会写入该目录。

底层判定逻辑（源码级）

这一逻辑实现在 src/prelude.rs 的app_dir()函数中，优先级如下：

1. 如果命令行指定了--config目录（见下文），直接使用该目录；
2. 否则获取当前可执行文件路径std::env::current_exe()，取其所在目录，拼接标志文件名ludusavi.portable（常量定义于 src/prelude.rs）；
3. 若该标志文件存在，则返回可执行文件所在目录作为应用文件夹；
4. 若不存在，回落到"系统配置目录 +/ludusavi"的默认路径。

由此可以总结两个要点：

• 标志文件只需存在，不要求内容非空，甚至可以在运行过程中临时创建/删除，因为每次启动都会重新判定；
• 优先级高于便携模式的是命令行--config参数：src/main.rs在main()入口处解析参数后，会将指定的配置目录写入全局CONFIG_DIR（见 src/main.rs），而app_dir()第一步就检查CONFIG_DIR是否已设置。因此--config是比便携标志更"硬"的覆盖手段。

三、应用文件夹里都有什么

应用文件夹并不仅仅是存放一处配置，它承载了 Ludusavi 运行所需的全部本地状态。核心文件如下：

1.config.yaml—— 用户配置

Ludusavi 的全部设置（备份目录、备份格式、游戏过滤、云同步、语言等）都保存在名为config.yaml的文件中，对应源码 src/resource/config.rs 中Config的FILE_NAME常量。文件结构定义在仓库的 JSON Schema 文档 docs/schema/config.yaml 中，每个字段的完整说明可参考 配置文件指南。

• 配置文件不存在时，Ludusavi 会以默认配置初始化（src/resource.rs 的load_from逻辑）；
• 若配置文件解析失败，Ludusavi 不会直接丢弃它，而是把原文件移动到config.invalid.yaml后重新开始（见 src/resource/config.rs 的archive_invalid()），避免用户手工编辑出错时丢失全部配置。

2.manifest.yaml—— 备份数据清单（请勿手动修改）

manifest.yaml是 Ludusavi 的备份数据清单，记录了每个游戏需要备份哪些文件/注册表项等元信息。它同样存放在应用文件夹下（src/resource/manifest.rs 定义FILE_NAME = "manifest.yaml"，路径由app_dir().joined(...)生成）。

官方文档特别强调：不要修改这个文件，因为每当 Ludusavi 下载到新版本清单时都会整体覆盖你做的改动。清单支持多数据源：主清单名为manifest.yaml，备用源则以manifest-<名称>.yaml命名（src/resource/manifest.rs）。

3. 日志文件与其余状态

程序日志也写入应用文件夹：src/main.rs在初始化日志器（flexi_logger）时，将日志目录指向app_dir()（见 src/main.rs 与 src/main.rs）。此外，云端备份缓存（Cache）等资源文件同样通过 src/resource.rs 的ResourceFile::path()统一落在app_dir()下。

小结：凡是 Ludusavi 需要"记住"的东西，几乎都以app_dir()为根目录。理解了第一节与第二节的路径解析规则，就等于掌握了整个程序的状态存储布局。

四、命令行实战：定位与导出配置

Ludusavi 的 CLI 提供了两个与配置目录直接相关的子命令，方便脚本化运维：

# 打印 config.yaml 的完整路径 ludusavi config path # 以 YAML 格式打印当前生效的配置内容 ludusavi config show # 以 JSON 格式打印配置内容 ludusavi config show --api # 打印配置文件的默认值（而非当前生效值） ludusavi config show --default

这些子命令在 src/cli.rs 中实现：config path直接调用Config::path().render()输出绝对路径；config show则把当前配置序列化为 YAML 或 JSON（--api走 JSON，--default先重置为默认配置再输出）。在多台机器间同步配置时，可以先config show导出，再放到另一台机器的应用文件夹中作为config.yaml使用。

启动时还可以用--config <目录>参数显式指定应用文件夹，此参数在main()入口处生效并覆盖便携模式判定（见 src/main.rs），适合在 CI 或脚本中隔离不同任务的配置。

五、典型使用场景与注意事项

U 盘 / 便携介质

• 在可执行文件所在目录创建ludusavi.portable（空文件即可），之后配置与清单都会保存在该目录，换电脑无需重新配置；
• 注意：Windows 下%APPDATA%默认路径与便携目录中的配置是互斥的——便携标志存在时，默认目录中的配置不会被读取，反之亦然。迁移时只需保证标志文件与期望的配置文件在同一个目录即可。

Flatpak 沙箱限制

Flatpak 版本的应用文件夹位于~/.var/app/com.github.mtkennerly.ludusavi/config/ludusavi，且默认仅有受限的文件系统访问权限（~与/run/media，见 安装指南）。如果备份目标超出这些范围，需要自行调整 Flatpak 权限。

manifest.yaml 的只读纪律

清单文件是 Ludusavi 判定"备份什么"的依据，任何手工修改都会在下次清单更新时被覆盖（官方文档明示）。若确实需要自定义备份规则，应通过自定义游戏功能实现，相关说明见 自定义游戏，而不是直接改清单。

配置损坏的兜底

手工编辑config.yaml语法出错时，Ludusavi 会自动把损坏文件改名为config.invalid.yaml并用默认配置继续运行（src/resource/config.rs）。恢复时把config.invalid.yaml修复后改回config.yaml即可，无需担心旧配置被立即抹除。

六、相关文档

• 配置文件指南：config.yaml各字段说明
• 配置 Schema：JSON Schema 定义
• 安装指南：各平台安装方式与便携性说明
• 命令行参考：config子命令及完整 CLI 用法
• 备份结构：备份文件在目标目录中的组织方式

• 桌面应用
• CLI