Kazumi 在 Linux 下打不开、提示存储初始化失败？三步找到 xdg-user-dirs 并修好

【免费下载链接】Kazumi基于自定义规则的番剧采集APP，支持流媒体在线观看，支持弹幕，支持实时超分辨率。项目地址: https://gitcode.com/gh_mirrors/ka/Kazumi

你看到的那一幕

在 Gentoo 上双击打开 Kazumi，界面刚加载就卡在"内部错误"弹窗：标题是无法初始化本地存储，正文给出一个存储路径，并提示"可在退出后删除该目录以重置本地数据"，按钮只有一个"退出程序"。翻终端输出和日志文件，反复出现getApplicationSupportDirectory调用失败、Failed to create directory这类字样。🔍 注意，这不是网络问题，也不是登录态问题——程序还没走到请求 Bangumi 数据那一步，它是在找自己家的环节就摔了。

我一步步排除了什么

1. 先怀疑权限。用ls -ld ~/.local/share ~/.config看目录权限，结果都正常，排除。
2. 再看目录本身。ls ~/.local/share/发现里面根本没有 Kazumi 的数据目录。程序连目录都没建出来就报错了，说明问题出在"路径没拿到"，而不是"拿到了但写不进去"。
3. 跑一条小命令验证。在终端执行下面这行：

xdg-user-dir DATA

正常系统会回吐一个路径（比如/home/<用户名>/.local/share）。我的 Gentoo 直接回我"找不到命令"。对，就是它——系统里压根没有提供这条命令的组件。

4. 回到代码对质。在 pubspec.yaml 里确认 Kazumi 依赖的是path_provider插件，它在 Linux 上的实现方式是调用xdg-user-dir命令来询问标准路径；而这条命令由xdg-user-dirs包提供。包不在，询问落空，插件只能回退到硬编码的兜底路径——在精简系统上，这个兜底路径常常创建不了，于是你在启动时看到的就是那个"内部错误"框。代码里的对应页面是 lib/pages/error/storage_error_page.dart，目录结构的说明可参考 static/doc/STRUCTURE.md。

真正卡在哪，一句话说清

说白了：XDG 是 Linux 定的一套"家规"——应用数据统一放~/.local/share/、配置放~/.config/、缓存放~/.cache/；而xdg-user-dirs就是负责回答"标准目录到底在哪"的那个组件。没有它，应用等于问了一圈没人应答，最后只能瞎猜地址。装上它，问题就解了。📦

三条命令搞定

按你的发行版选一组：

Gentoo

sudo emerge xdg-user-dirs

Debian / Ubuntu

sudo apt install xdg-user-dirs

Fedora / openSUSE 等 RPM 系

sudo dnf install xdg-user-dirs

装完之后统一再执行：

# 1. 初始化/刷新标准目录配置 xdg-user-dirs-update # 2. 验证：应输出一个具体目录路径，而不是"command not found" xdg-user-dir DATA

验证通过后再启动 Kazumi，~/.local/share/io.github.Predidit.Kazumi/应当被正常创建。如果程序之前已经往错误位置写过数据，把它手动挪过去，或者删掉那个错误目录让它重新初始化（本地收藏、历史记录会随之清零，注意先确认里面没有你需要的东西）。

顺便提醒一句

• 如果你在做发行版打包，记得在包元数据里显式声明对xdg-user-dirs的依赖，别指望用户自己排查到这一步。
• 如果你用的是Gentoo 最小安装或精简容器环境，这类基础组件最容易被漏装，遇到"应用启动即报路径/存储错误"时，先查它。
• 另外 Wayland 还是 X11 跟这个问题无关，桌面环境不会改变xdg-user-dir是否存在的判定。

【免费下载链接】Kazumi基于自定义规则的番剧采集APP，支持流媒体在线观看，支持弹幕，支持实时超分辨率。项目地址: https://gitcode.com/gh_mirrors/ka/Kazumi