先判断失败发生在哪个环节

Krita AI Diffusion 是面向 Krita 的 AI 绘画插件。它通常由两部分组成：Krita 内的 Python 插件界面，以及本地运行的 AI 后台服务。

很多“安装失败”并不是同一个问题。有的表现为导入压缩包时报错，有的是重启 Krita 后看不到面板，也有的是面板能打开但无法生成图像。

因此，排查时不要急着反复重装。应先确认失败位置：

• 插件是否成功导入？
• Python 插件是否启用？
• 后台服务是否能启动？
• 模型文件是否完整？
• 显卡环境是否可用？

建议先记录以下信息： Krita 版本、系统版本、显卡型号、插件版本和报错原文。Krita AI Diffusion 对 Krita 版本较敏感，较新的插件一般建议搭配 Krita 5.2 或更新版本使用。如果 Krita 本体过旧，可能出现菜单项缺失、脚本接口不可用、面板空白等情况。

标准安装流程复核

第一步： 从项目发布页获取对应版本的安装压缩包。注意下载的是用于 Krita 插件导入的 zip 文件，不要下载源码包后直接导入。源码包常见问题是内部多了一层目录，Krita 无法识别插件描述文件。

第二步： 打开 Krita，进入“工具”或“脚本”相关菜单，选择导入 Python 插件，选中下载好的 zip 包。导入完成后重启 Krita。再到“设置”里的 Python 插件管理器中，确认 AI Image Diffusion 或类似名称的项目已勾选。

第三步： 重新启动 Krita 后，在停靠面板或菜单中打开插件界面。如果界面可以打开，再按提示安装或配置本地服务与模型。首次运行通常需要下载组件，时间取决于网络环境和磁盘速度，期间不要频繁关闭 Krita。

第四步： 确认保存路径不要放在权限受限的系统目录。

• Windows 用户建议将服务和模型放在用户目录或独立数据盘。
• macOS 用户注意应用权限。
• Linux 用户检查目录读写权限。

路径中尽量避免特殊符号和过长目录名，以减少脚本解析问题。

常见报错与处理办法

导入时提示“不是有效插件”或导入后无变化

优先检查压缩包结构。正确的包内应能找到插件描述文件和 Python 脚本目录，而不是“项目名-版本号”文件夹再套一层内容。解决办法是重新下载 release 中的插件包，或解压后按官方目录结构重新打包。

重启后找不到面板

通常是 Python 插件未启用。进入 Krita 设置中的 Python 插件管理器，勾选对应项目并再次重启。若插件列表中也没有，说明导入没有成功，需要检查用户插件目录。Windows 常见位置在用户 AppData 的 krita 资源目录下，Linux 常见位置在 home 下的 share 目录，macOS 则在 Library 的应用支持目录中。不同版本路径可能略有差异，可在 Krita 的“资源文件夹”入口中直接打开。

面板打开后提示无法连接本地服务

提示连接被拒绝或服务启动失败，说明 Krita 插件界面已运行，但 AI 后台没有正常启动。常见原因包括端口被占用、服务文件缺失、运行权限不足、显卡驱动或计算组件不匹配。可以先在插件设置中更换端口，关闭占用资源较多的软件，再尝试重新启动服务。

出现“CUDA 不可用”“显存不足”或生成时进度中断

多半与显卡环境有关。独立显卡用户应确认驱动较新，并选择适合自己显存的模型和分辨率。显存较小的设备不建议直接使用大模型、高分辨率和过多控制模块。可先用低分辨率测试，例如 512 或 768 边长，确认流程可用后再逐步提高参数。

模型下载失败、校验失败或生成结果一直等待

可能是文件不完整。不要只点击重试，先查看模型目录中是否存在体积异常的小文件或临时文件，删除后重新下载。磁盘空间也要预留充足，AI 模型和缓存会占用较大容量，空间不足会导致安装看似完成但运行报错。

如何查看日志并定位问题

日志是解决 Krita AI 安装问题的关键。

如何查看日志： Krita 本体日志通常可在帮助菜单、资源目录或终端启动输出中查看；插件自身也可能在设置界面提供“打开日志”“复制诊断信息”等按钮。排错时重点关注最后一次失败附近的内容，而不是整份日志全部复制。

如何阅读日志： 可以按关键词定位。

• 出现 ImportError、ModuleNotFoundError，说明 Python 模块或插件文件不完整。
• 出现 Permission denied，说明目录权限不足。
• 出现 Address already in use，说明端口被占用。
• 出现 No such file or directory，说明路径错误或组件缺失。
• 出现 CUDA、torch、onnx 等字样，通常与计算环境或组件版本相关。
• 出现 timeout、download failed，则多与下载中断或远程资源不可达有关。

向社区求助时： 建议提供 Krita 版本、插件版本、系统、显卡、安装方式、报错截图和关键日志。不要只写“不能用”，也不要一次贴出包含个人路径和项目文件名的完整日志。发布前可遮盖用户名、工程目录等个人信息。

升级前的准备与正确做法

升级前准备： 先确认新版说明中要求的 Krita 版本和后台服务版本。如果插件、服务、模型配置之间跨度过大，可能出现旧配置无法读取或节点不兼容。稳妥做法是：先备份 Krita 配置目录中的插件配置文件，以及 AI 服务目录中的模型、工作流和自定义预设。

升级时做法： 建议关闭 Krita，再替换或导入新版本插件。完成后首次启动不要同时打开大型工程，先新建空白画布测试面板是否加载、服务是否启动、基础生成是否正常。确认可用后，再打开正式文件继续创作。

更新后台服务： 如果新版需要更新后台服务，不要把旧目录直接全部覆盖。更推荐使用插件内置的更新入口，或按说明单独更新服务文件，模型目录则保留。这样既能减少重复下载，也能避免旧文件混入新版本导致难以判断问题来源。

回滚方案：恢复到可用版本

升级后若出现严重异常，回滚应按“插件、配置、服务”三个层面处理。

回滚插件： 先关闭 Krita，删除当前插件目录中的新版本文件，再导入之前可用的 zip 包。随后检查 Python 插件管理器，确认启用的是旧版本。

回滚服务： 如果只是插件界面异常，通常回滚插件即可。如果后台服务也升级过，需将服务目录恢复到旧版本。若提前做过备份，可直接替换服务文件并保留模型目录。若没有备份，只能重新下载旧版本组件，耗时会更长。

回滚配置： 配置文件也可能造成回滚失败。例如新版写入了旧版无法识别的参数，旧版启动后仍然报错。此时可先临时移走插件配置文件，让插件以默认配置启动。确认旧版可运行后，再逐项恢复自定义路径和预设。

常见问题简答

问：安装后 Krita 没有任何新菜单怎么办？
答：先确认压缩包导入成功，再到 Python 插件管理器启用项目，最后重启 Krita。仍没有出现时，检查是否导入了源码包或放错目录。

问：能打开面板但无法生成图像怎么办？
答：这说明插件界面大概率正常，重点排查本地服务、模型文件、端口和显卡环境。先用默认参数生成小图，排除参数过高导致的资源不足。

问：升级一定要删除旧模型吗？
答：通常不需要。模型体积较大，且与插件主体分离。除非日志明确提示模型损坏或格式不兼容，否则建议保留模型目录，只更新插件和服务。

问：是否可以混用多个版本？
答：不建议在同一个 Krita 配置目录中频繁混用。若必须测试多个版本，可以使用不同的资源目录或先完整备份，避免配置互相覆盖。

安全边界与实用建议

安装 AI 绘画插件时，应尽量使用项目发布页、Krita 官方资源入口或可信社区提供的链接，不要运行来历不明的脚本。插件拥有读取工程文件和调用本地服务的能力，随意安装修改版可能带来数据泄露、文件损坏或系统异常风险。

不要为了追求新功能忽略版本说明。 创作生产环境更适合使用稳定版本，把新版本放在备用环境测试。重要工程文件应定期另存副本，尤其是在批量处理图层、使用生成填充或替换局部内容前，先保留原始文件。

排查时遵循从简单到复杂的顺序：先看版本，再看是否启用插件，再看日志，再检查服务与模型，最后才考虑重装 Krita 或系统环境。这样可以避免重复下载大文件，也能更快找到真正原因。多数安装失败都能通过正确版本、干净目录、完整日志和谨慎升级解决。