U 盘打印功能使用指南

FLYOS-FAST 可以自动挂载 U 盘，并在网页文件管理器或本机屏幕中浏览和打印其中的 G-code 文件。本文所述逻辑已按 H3、H5、H618 的 v1.3.10 正式镜像以及 H618 v1.4.0 测试镜像核对。

工作原理

U 盘分区会作为一个以 U_ 开头的文件夹挂载到 G-code 目录。选择其中的文件开始打印时，系统会先将完整文件复制到本地：

/usr/share/printer_data/gcodes/.UDISK/tmp.gcode

复制完成后，Klipper 才会从这个本地临时文件执行打印。开始下一次 U 盘打印时，临时文件会被覆盖。

等待复制完成后再拔出 U 盘

复制刚开始时，网页可能已经显示为“打印中”，该状态不代表文件已经复制完成。请在控制台看到以下提示后再拔出 U 盘：

Copy files from removable disk completed

也可以等待打印机已经开始执行加热或运动后再拔出。复制过程中拔出 U 盘会导致复制失败，当前打印无法正常开始。

U 盘和文件要求

项目	支持范围	建议
文件系统	FAT32、exFAT、NTFS	优先使用 FAT32 或 exFAT
文件格式	.gcode、.g、.gco	优先使用 .gcode
文件位置	U 盘根目录或多级文件夹	按模型分类存放即可
U 盘容量	没有固定的最低容量限制	保留足够空间并确认文件完整
文件名	支持 UTF-8、空格和中文	为提高跨平台兼容性，建议使用简短文件名

不支持直接打印 .stl、.obj 等模型文件或切片工程文件；必须先通过切片软件生成 G-code。

Windows 文件后缀显示

Windows 可能隐藏已知文件的扩展名。请在文件资源管理器中勾选 文件扩展名，确认文件最终扩展名确实为 .gcode、.g 或 .gco，避免出现 模型.gcode.txt。

使用步骤

1. 将切片生成的 G-code 文件复制到 U 盘根目录或文件夹中。
2. 将 U 盘插入上位机 USB 接口。
3. 打开 Fluidd、Mainsail 或本机屏幕的文件列表。
4. 找到以 U_ 开头的文件夹；如果没有立即出现，请刷新文件列表。
5. 打开 U 盘文件夹，选择需要打印的 G-code 文件。
6. 确认文件和预览信息无误后，仅点击一次“开始打印”。
7. 等待控制台显示复制完成，系统随后会自动开始执行本地临时文件。

一次只启动一个复制任务

复制过程中不要重复点击“开始打印”，也不要选择第二个 U 盘文件。当前版本的所有 U 盘打印任务共用同一个 tmp.gcode，并发复制可能覆盖文件并导致打印异常。

拔出 U 盘

• 已确认文件复制完成后，普通 U 盘可以拔出，当前任务将继续读取本地临时文件。
• 如果控制台仍显示 Copying file，不要拔出 U 盘。
• 如果没有出现任何复制进度或完成提示，不要在打印过程中拔出。部分 USB 硬盘盒或 USB SSD 可能没有被系统识别为可移动设备，此时 Klipper 可能直接读取外部文件。
• 如果通过网页对 U 盘执行了上传、删除或重命名操作，应等待操作完成后再拔出。

已知限制

• 自动挂载只处理带常规分区的 USB 存储设备。没有分区表的 U 盘可能无法显示，可在电脑上重新创建分区并格式化。
• 不要同时插入两只厂商、型号、容量和分区结构完全相同的 U 盘；它们可能生成相同的挂载目录并发生冲突。
• 当前自动识别规则只覆盖常见的单数字分区，例如 /dev/sda1。特殊的多分区存储设备可能无法自动挂载所有分区。
• U 盘打印依赖本地剩余空间。G-code 文件越大，开始打印前等待复制的时间越长。

文件显示但无法开始打印

1. 确认扩展名为 .gcode、.g 或 .gco。

2. 确认 G-code 文件可以在切片软件中正常预览。

3. 检查上位机本地剩余空间：

   df -h /usr/share/printer_data/gcodes

4. 查看 Klipper 日志中的文件复制或打开错误：

   tail -n 100 /usr/share/printer_data/logs/klippy.log

本地上传正常，但 U 盘打印无法开始

部分切片软件会使用 GBK、ANSI 等非 UTF-8 编码保存中文注释：

• 通过网页上传到本地 G-code 目录后，Klipper 会忽略无法解码的字符，因此文件可能正常打印。
• 从 U 盘选择文件时，系统会先复制到 .UDISK/tmp.gcode，随后严格按照 UTF-8 读取；遇到非 UTF-8 字节时可能无法开始打印。

Klipper 日志中可能出现类似错误：

UnicodeDecodeError: 'utf-8' codec can't decode byte

中文文件名通常不是原因

中文、下划线和连字符可以正常用于文件名。仅将文件重命名为英文不会改变文件内部编码，也不能解决这个问题。

请使用以下任一方法处理：

1. 优先在切片软件中重新导出，并将 G-code 文本编码设置为 UTF-8。
2. 使用支持编码转换的文本编辑器，将整个 G-code 文件转换并保存为 UTF-8；不要只修改扩展名。
3. 如果切片软件无法选择编码，可删除文件头部的非 UTF-8 中文注释后重新保存。不要修改实际运动、温度和挤出指令。
4. 临时情况下可通过网页将文件上传到本地 G-code 目录后再打印。

对于体积较大的 G-code，建议重新切片或使用专用文本工具转换，不要直接在浏览器中编辑整个文件。

复制失败后一直显示“打印中”

先确认打印机没有执行加热、运动或其他打印操作，然后重新启动 Klipper：

systemctl restart klipper

重新插入 U 盘并再次打印。如果问题重复出现，请更换 U 盘，并向技术支持提供以下两个日志：

/var/log/flyos-auto-mount.log
/usr/share/printer_data/logs/klippy.log