先判断失败发生在哪个阶段
SD.Next 是常见的本地 AI绘画工具前端，安装流程通常包括拉取项目文件、创建 Python 虚拟环境、安装 PyTorch 与扩展依赖、启动 Web 界面等步骤。不同阶段失败，处理方向完全不同。不要看到报错就反复重装，先确认卡在“下载项目”“安装依赖”“启动服务”还是“加载模型”。如果是窗口一闪而过，优先用命令行进入安装目录手动启动，这样能看到完整报错。
建议先记录三项信息：系统版本、显卡型号与显存、Python 版本。Windows 用户还要确认路径中不要包含中文、空格过多或特殊符号，推荐放在类似 D:\AI\sdnext 这样的短路径。安装目录不要放到需要高权限控制的系统目录，避免文件写入失败。
安装前的基础环境检查
SD.Next 对 Python 版本较敏感，常见推荐是 Python 3.10 系列。若机器里同时装了多个版本，启动脚本可能调用到错误版本，表现为依赖无法安装、模块找不到或语法不兼容。可在命令行执行 python --version 与 where python 查看实际调用路径。若显示 3.11、3.12 或商店版 Python，建议重新安装官方 3.10，并在安装时勾选添加到 PATH。
显卡驱动也会影响启动。NVIDIA 用户应确认驱动较新，并匹配 CUDA 版 PyTorch；AMD、Intel 或仅 CPU 环境则要选择对应后端，性能和兼容性会不同。首次安装前还应预留足够磁盘空间，项目、依赖、模型和缓存合计可能占用几十 GB。空间不足时，报错不一定直接写“磁盘满”，也可能显示解压失败、文件损坏或依赖安装中断。
常见报错与处理思路
第一类是“Python not found”“No module named pip”。这通常是 Python 未安装、PATH 未配置或虚拟环境损坏。处理方式是确认 python 与 pip 可正常执行，删除安装目录下的 venv 文件夹后重新启动安装脚本，让程序重建环境。不要随意把系统 Python 的 site-packages 复制进项目，容易造成版本混乱。
第二类是“torch 安装失败”“CUDA una vailable”“显卡不可用”。先确认显卡驱动正常，再检查 PyTorch 是否安装到了正确版本。若之前装过不同后端，建议清理 venv 后重装。启动后如果页面能打开但生成时报显存不足，可降低分辨率、批量数量和高分辨率修复倍率，先用小尺寸测试，不要一上来加载多个大模型和扩展。
第三类是“依赖下载超时”“Read timed out”“Connection reset”。这多与网络连接不稳定、源站响应慢或依赖包体积大有关。可以更换 pip 镜像源，或多执行一次安装命令。若公司或校园网络限制较多，建议换到更稳定的网络环境。不要从不明来源下载被改动过的安装包，AI绘画工具会执行本地脚本，安全风险不能忽视。
第四类是“Permission denied”“Access is denied”。通常是目录权限、杀毒软件拦截或文件被占用。可关闭正在运行的 SD.Next 进程，使用普通用户有写入权限的目录，必要时把项目目录加入安全软件的信任列表。不要把整个系统盘都加入例外，只针对明确的项目目录处理。
如何查看日志定位问题
日志排错的核心是看“第一条真正的错误”，而不是只看最后一行。SD.Next 启动时控制台会输出大量信息，最后的报错可能只是连锁结果。优先向上翻找 traceback、ERROR、failed、exception 等关键词，定位最早出现异常的模块名和文件名。
常见日志来源包括启动命令行窗口、项目目录中的 logs 文件夹、浏览器控制台以及扩展自己的日志。若是页面打不开，重点看命令行是否显示本地访问地址；若页面能开但按钮无响应，再看浏览器开发者工具中的网络请求状态。反馈问题时，应提供系统、显卡、Python 版本、启动参数、完整报错片段和最近做过的操作，不要只截一张最后一行的图。
如果日志中间出现某个扩展名称，可先禁用该扩展验证。很多安装失败并非主程序问题，而是扩展依赖与当前版本不兼容。可临时移动 extensions 目录下对应扩展文件夹，再重新启动。确认主程序正常后，再逐个恢复扩展，找出冲突源。
干净重装的正确方式
当环境已经多次修补仍失败，可以做一次“保留资产的干净重装”。先备份 models、outputs、embeddings、styles、配置文件和自定义脚本，不要直接删除整个目录。随后删除 venv、repositories、临时缓存和报错扩展，再重新执行启动脚本。这样既能重建依赖，又不会丢失模型和作品。
如果怀疑项目文件本身损坏，可重新拉取项目到新目录，再把模型文件夹迁移过去。迁移后先不要复制旧配置，使用默认设置启动一次，确认可进入界面并完成一张低分辨率出图，再逐步恢复配置。这样能避免旧参数继续触发同样问题。
升级前要做的准备
SD.Next 更新较频繁，新版本会修复问题，也可能带来依赖变化。升级前应记录当前可用版本，备份配置、模型索引和扩展列表。推荐先阅读更新说明，关注 Python、PyTorch、驱动和扩展兼容性要求。生产用途或正在赶项目时，不建议在没有备份的情况下直接升级。
升级后第一次启动时间可能较长，因为依赖会重新解析和安装。若升级后报错，先不要立刻删除全部文件，先判断是依赖未更新完整、扩展冲突还是配置项变化。可以先禁用第三方扩展，用默认主题和默认参数启动，缩小排查范围。
回滚方案：从可用版本恢复
回滚的前提是知道之前哪个版本可用。使用 Git 管理的安装目录，可以通过查看提交记录找到旧版本，再切换回指定提交。操作前先备份当前目录，尤其是 outputs、models 与配置文件。回滚主程序后，建议删除 venv 让依赖按旧版本重新生成，否则新旧依赖混用可能继续报错。
如果不会使用版本命令，最稳妥的方法是保留一个“稳定版目录”和一个“测试版目录”。稳定版只用于日常出图，不频繁更新；测试版用于体验新功能。模型文件可用统一模型目录或快捷方式引用，避免重复占用大量空间。这样即使测试版安装失败，也不会影响稳定工作流。
安全边界与实用建议
安装 AI 工具时不要运行来源不明的脚本，不要随意粘贴陌生命令，尤其是会删除目录、修改系统环境或下载可执行文件的命令。扩展安装也要克制，越多扩展越容易出现依赖冲突。对不确定的扩展，先看维护频率、问题反馈和安装说明，再决定是否使用。
日常维护建议固定一套可用环境：Python 版本不随意升级，显卡驱动不要在项目关键期更新，主程序升级前先备份。遇到安装失败时按“环境检查、日志定位、禁用扩展、重建 venv、干净重装、版本回退”的顺序处理，通常能解决大多数问题。真正难定位的故障，也应基于完整日志沟通，而不是反复覆盖安装。
常见问题快速答疑
问：删除 venv 会不会删掉模型？不会。venv 主要是 Python 虚拟环境，模型通常在 models 目录。但操作前仍建议确认路径，避免误删。
问：页面打不开一定是安装失败吗？不一定。可能是启动还没完成、端口被占用或浏览器缓存异常。先看控制台是否给出本地地址，再尝试更换端口或重启进程。
问：升级后出图变慢怎么办？先检查是否切换了后端、是否启用了高消耗扩展、默认精度和优化项是否变化。用同一模型、同一尺寸、同一步数做对比，才能判断是否真是版本问题。
问：是否需要每次报错都重装？不需要。多数问题通过日志可定位到单个依赖、扩展或配置。频繁重装会增加变量，反而更难判断根因。
