---
title: "数据目录"
description: "XBase 的目录约定、模组数据位置、应用数据目录与查看器。"
---


> 所有接入 XBase 的模组共用一份目录：`<游戏根目录>\XBase\`。本节说明路径约定、取路径的 API 与出厂查看器。

## 目录结构

```
<游戏根目录>\XBase\
  XBase.exe              ← 日志与配置查看器
  debug.log              ← XBase 自身日志
  config.json            ← XBase 自身配置
  hotkeys.json           ← XBase 热键绑定
  Library\               ← 公用二进制，只放 XBase 共享运行时与 WebView2Loader
    XBaseSA.dll / XBaseVC.dll / XBaseIII.dll
    WebView2Loader.dll
  Mods\
    XMenu\
      config.json
      debug.log
    WebView2\
      WebView2SA.dll / WebView2VC.dll / WebView2III.dll   ← 两段式模组的 payload
      config.json
      debug.log
```

模组目录名与 asi 文件名一致，不含扩展名。`Library\` 只放公用库；模组自己的 payload dll 与数据一律在 `Mods\<模组名>\` 下。

## 应用数据目录

缓存类数据不落在游戏目录，统一放 AppData：

```
%APPDATA%\com.yuinijika.xbase\
  webview2\              ← WebView2 用户数据（EBWebView）
```

游戏目录常被整体压缩分享，WebView2 用户数据里的缓存与登录态跟着打包走存在泄漏风险，因此隔离到游戏目录之外。

## 取路径

宿主不要自行拼接路径，使用公共方法：

```cpp
const std::string gameDir = XBase::Platform::GameDirectory();       // 游戏根目录
const std::string baseDir = XBase::Platform::XBaseDirectory();      // <游戏根目录>\XBase\
const std::string appDir  = XBase::Platform::AppDataDirectory();    // <AppData>\com.yuinijika.xbase\
const std::string modDir = XBase::Platform::ModDirectory("XMenu");  // <游戏根目录>\XBase\Mods\XMenu\
const std::string cfgPath = XBase::Platform::ModConfigPath("XMenu");
const std::string logPath = XBase::Platform::ModLogPath("XMenu");
```

`ModDirectory()` 会按需创建目录。`AppDataDirectory()` 取不到 AppData 时返回空字符串，调用方自行决定是否退回游戏目录。

## 初始化日志与配置

```cpp
XBase::Log::InitForMod("XMenu");      // <游戏根目录>\XBase\Mods\XMenu\debug.log
XBase::Config::InitForMod("XMenu");   // <游戏根目录>\XBase\Mods\XMenu\config.json

XBase::Log::Shutdown();
```

`Log::Init()` 与 `Config::Init()` 写的是 XBase 自身数据，模组一律用 `InitForMod()`。

## 兼容旧安装

- 旧版本把 `config.json` / `hotkeys.json` 放在 asi 目录下的 `XBase\`，首次运行时会把它们迁移到新位置
- `WebView2Loader.dll` 如果还在 asi 目录旁或旧版 `XBase\` 根目录，加载时会被搬到 `<游戏根目录>\XBase\Library\` 再使用
- 日志不做迁移，`logs\xbase.log` 不再写入
- 旧版本把 WebView2 用户数据放在 `<游戏根目录>\XBase\webview2`，现已改到 AppData；旧目录不做自动迁移，可手动删除

## 查看器

`<游戏根目录>\XBase\XBase.exe`：

- 左侧列出 XBase 自身与 `Mods\` 下的每个模组
- 中间列出该目录下的 `config.json`、`debug.log`、`hotkeys.json`
- 右侧只读显示内容，按钮支持刷新、打开目录与复制内容
- 查看器不依赖游戏，也不需要 XBase SDK，随发布包一起提供

## 常见问题

| 现象 | 排查 |
|---|---|
| 配置没有写入 | 是否调用了 `Config::InitForMod("模组名")`，模组名是否与 asi 同名 |
| 日志找不到 | 看 `<游戏根目录>\XBase\Mods\<模组名>\debug.log`，不再有 `logs` 目录 |
| 网页加载被拦 | 是否先 `MapFolder()` 映射虚拟主机，而不是直接用 `file:` 协议 |
| 加载器缺失 | 确认 `<游戏根目录>\XBase\Library\WebView2Loader.dll` 存在，或让 XBase 自行迁移旧副本 |
| 网页数据还在游戏目录 | 旧版本把 `webview2` 放在 `<游戏根目录>\XBase\`，删除即可；新位置为 `%APPDATA%\com.yuinijika.xbase\webview2` |