一键启动.sh使用教程，Z-Image快速上手不踩坑

一键启动.sh使用教程，Z-Image快速上手不踩坑

你是不是也遇到过这样的情况：下载好Z-Image-ComfyUI镜像，兴冲冲点开Jupyter，却卡在1键启动.sh这一步——双击没反应？终端里运行报错？点开网页一片空白？明明文档写得清清楚楚，自己操作就是走不通？

别急，这不是你的问题。这个“一键启动”脚本本身设计得很聪明，但它的运行逻辑、依赖条件和常见陷阱，官方文档里确实没展开讲。今天这篇教程，就带你从零开始、逐行拆解、避开所有已知坑点，真正实现“点一下、等三秒、出图成功”。

全文不讲原理、不堆参数、不谈架构，只聚焦一件事：让你的Z-Image-Turbo在本地跑起来，第一张图稳稳生成出来。

1. 先搞懂这个脚本到底在做什么

1键启动.sh不是魔法，它是一段精心编排的Shell指令集合。理解它，才能用好它，更关键的是——出问题时能自己修。

它实际执行了四个核心动作：

• 检查环境是否就绪：确认CUDA驱动、PyTorch、xformers、ComfyUI主程序都已正确安装；
• 加载Z-Image模型权重：自动识别并挂载/root/models/zimage/下的Turbo/Base/Edit三个子目录；
• 启动ComfyUI服务进程：以后台方式运行，监听8188端口，并启用GPU加速；
• 输出访问提示：告诉你该打开哪个网址、怎么查看日志、哪里找生成图。

注意：它不会自动启动Jupyter（那是另一个服务），也不会帮你下载模型文件——模型必须提前放在指定路径，否则脚本会静默跳过加载，导致网页里找不到Z-Image节点。

所以，“一键启动”的前提是：环境已部署完成 + 模型已就位 + 脚本权限正确。缺一不可。

2. 启动前必做的三件事（90%失败源于此）

很多用户反馈“运行后没反应”，其实根本没走到启动环节。下面这三步，请务必手动确认一遍，不要跳过。

2.1 确认模型文件已正确放置

Z-Image-ComfyUI镜像默认不内置模型权重（出于版权与体积考虑）。你必须手动把模型放进/root/models/zimage/目录下，结构如下：

/root/models/zimage/ ├── turbo/ # Z-Image-Turbo 检查点 │ └── model.safetensors ├── base/ # Z-Image-Base 检查点 │ └── model.safetensors └── edit/ # Z-Image-Edit 检查点 └── model.safetensors

正确做法：

• 下载地址请参考GitCode仓库中的MODEL_DOWNLOAD.md（通常在镜像文档页底部有链接）；
• 使用Jupyter左侧文件浏览器，进入/root/models/→ 新建文件夹zimage→ 再分别建turbo、base、edit三个子目录；
• 将对应.safetensors文件拖入对应文件夹（注意：不是zip包，是解压后的单个文件）。

❌ 常见错误：

• 把模型放在/root/models/checkpoints/（这是Stable Diffusion传统路径，Z-Image不认）；
• 文件名不是model.safetensors（比如带版本号或后缀错误）；
• 权限为只读（上传后右键→Properties→勾选“可执行”无用，需终端改权限）。

2.2 检查脚本是否具备可执行权限

Linux系统中，.sh文件默认没有执行权限。直接双击或./1键启动.sh会报错：Permission denied。

正确做法（在Jupyter终端中执行）：

cd /root chmod +x "1键启动.sh"

注意引号：脚本名含中文和符号，必须加英文双引号包裹，否则bash会报错No such file or directory。

2.3 验证GPU与CUDA环境可用

即使镜像预装了CUDA，也可能因驱动版本不匹配导致启动失败（尤其在非NVIDIA官方云平台或老旧显卡上）。

快速验证方法（终端中运行）：

nvidia-smi python3 -c "import torch; print(torch.cuda.is_available(), torch.__version__)"

预期输出应类似：

True 2.1.0+cu118

❌ 若第一行报command not found，说明NVIDIA驱动未加载；若第二行输出False，说明PyTorch未正确绑定CUDA——此时运行启动脚本必然失败，需先解决底层环境问题。

3. 手动运行启动脚本的正确姿势

现在，所有前置条件都已满足。我们来执行真正的“一键启动”。

3.1 在Jupyter终端中运行（推荐）

打开Jupyter → 右上角New→Terminal→ 输入以下命令：

cd /root ./"1键启动.sh"

你会看到类似这样的输出：

检测到GPU设备：NVIDIA RTX 4090 PyTorch CUDA可用：True ComfyUI主程序存在 Z-Image-Turbo模型已就位 正在启动ComfyUI服务... → 日志将输出至 /root/comfyui.log → 访问地址：http://localhost:8188

成功标志：最后出现→ 访问地址：http://localhost:8188，且终端光标仍在闪烁（说明服务已在后台运行，未崩溃）。

3.2 如果运行后立即退出？看日志！

脚本内部做了静默重定向，所有错误信息都写入/root/comfyui.log。别猜，直接查：

tail -n 20 /root/comfyui.log

最常见报错及修复：

小技巧：脚本运行后，可另开一个终端窗口，实时监控日志：
tail -f /root/comfyui.log

4. 进入ComfyUI后，如何真正生成第一张图？

很多人以为脚本运行完就结束了，其实最关键的一步才刚开始：在网页里正确调用Z-Image节点。

4.1 找到专属工作流（不是默认那个！）

Z-Image-ComfyUI预置了多个工作流，但只有Z-Image-Turbo-Workflow.json支持Turbo模型的8步极速采样。默认打开的ComfyUI_default.json是通用版，不包含Z-Image专用节点。

正确路径：

• 点击左侧面板顶部的Load（加载）按钮；
• 在弹窗中选择/root/workflows/Z-Image-Turbo-Workflow.json；
• 点击Load Workflow。

你会看到画布上出现6个清晰节点：Z-Image-Loader、CLIP Text Encode（正/负）、KSampler、VAE Decode、Save Image。

4.2 修改提示词，点击“队列”出图

• 双击CLIP Text Encode (Positive)节点 → 在文本框中输入中文提示词，例如：
  一只橘猫坐在窗台上，阳光洒落，高清写实风格，细节丰富
• 双击CLIP Text Encode (Negative)→ 输入负面词，例如：
  blurry, deformed, text, watermark
• 点击右上角绿色Queue Prompt按钮。

预期效果：

• 左下角状态栏显示Running...→Done（Turbo模型通常3~5秒内完成）；
• Save Image节点右侧出现小缩略图；
• 图片自动保存至/root/output/目录（可通过Jupyter文件浏览器查看）。

提示：首次运行可能稍慢（模型加载进显存），后续生成稳定在4秒内。若超过10秒无响应，请检查comfyui.log中是否有CUDA out of memory。

5. 高频问题与避坑指南（亲测有效）

以下是我们在上百次部署中总结出的最常踩、最隐蔽、最耽误时间的五个坑，附带一键修复命令。

5.1 问题：网页打不开，提示“连接被拒绝”

• 原因：ComfyUI服务未启动，或端口被占用
• 修复：

# 查看8188端口是否被占用 lsof -i :8188 # 若有进程，杀掉它 kill -9 $(lsof -t -i :8188) # 重新运行启动脚本 ./"1键启动.sh"

5.2 问题：工作流加载后，Z-Image-Loader节点显示红色报错

• 原因：模型路径硬编码为/root/models/zimage/turbo/，但你放错了位置
• 修复：
• 右键点击该节点 →Edit Node→ 找到model_path字段；
• 手动改为你的实际路径，例如：/root/models/zimage/turbo/model.safetensors；
• 或直接在Jupyter中执行：

  sed -i 's|/root/models/zimage/turbo/model.safetensors|/your/actual/path/model.safetensors|g' /root/workflows/Z-Image-Turbo-Workflow.json

5.3 问题：生成图片全是灰色噪点或纯黑

• 原因：VAE解码器不匹配（Z-Image使用自研VAE，不能混用SD通用VAE）
• 修复：确保工作流中VAE Load节点加载的是zimage_vae.safetensors（已预置在/root/models/vae/），而非其他VAE文件。

5.4 问题：中文提示词不生效，生成结果与描述无关

• 原因：CLIP文本编码器未切换为Z-Image专用版本
• 修复：在CLIP Text Encode节点设置中，将clip_name改为zimage-clip（该选项仅在Z-Image工作流中可见）。

5.5 问题：生成图分辨率低、模糊、有马赛克

• 原因：默认工作流设为512×512，未适配Z-Image的原生高分能力
• 修复：双击KSampler节点 → 将width和height改为1024（Z-Image-Turbo原生支持1024×1024，无需额外放大）。

6. 总结：你已经掌握了Z-Image落地的核心钥匙

回顾整个流程，我们其实只做了五件小事：

• 把模型文件放进对的文件夹；
• 给脚本加上可执行权限；
• 确认GPU能被Python看见；
• 用对的工作流文件，而不是默认那个；
• 第一次生成时，耐心等那几秒钟。

没有复杂的配置，没有深奥的术语，也没有需要背诵的参数。Z-Image-ComfyUI的设计哲学，本就是让强大变得简单——而“一键启动.sh”，正是这道简单之门的钥匙。

你现在完全可以：
在RTX 4090上3秒生成一张1024×1024高清图；
在RTX 3060（12G）上稳定运行Turbo模型；
把工作流导出分享给同事，对方一键加载就能复现；
后续想换Base做精细微调，或切Edit做图生图，只需改一行路径。

这才是开源AI工具该有的样子：不炫技，只务实；不设障，只铺路。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。