Creamy络说实话，很多用 Ender-3S 的朋友听到“刷 Klipper”第一反应是：我这板子够格吗？答案是可以，而且刷完以后，这台机器的脾气会变了一个样。Klipper 不是简单替换 Marlin 的新固件，它把 3D 打印机的运动计算整个搬到上位机（树莓派、旧电脑这类设备）里，主板只负责实时执行指令。这套架构对 Ender-3S 这种入门级机器尤其有意义——原厂固件在三五十毫米每秒的速度下还算稳，一旦加速度调高、速度超过 80mm/s，位姿控制就开始拉胯，而 Klipper 靠输入整形和压力提前能把同样的硬件推出明显更好的表现。这篇博文就是围绕 Ender-3S 升级 Klipper 的完整记录，从刷机准备、主板固件烧录、参数校准到最终性能调优都覆盖到，适合手里正好有这类机型、想提速并改善打印质量的玩家参考。我会把每一步“为什么要这么做”讲透，同时把踩坑的部分单独拎出来，尽量减少后来人绕弯路的概率。
1. Ender-3S 升级 Klipper 的价值评估与适用场景
1.1 为什么是 Klipper？先搞懂它到底改了什么
Marlin 把运动规划、温度控制、G 代码解析全部放在主板上，而 Ender-3S 这类机器的主控大多是 8 位或入门级 32 位芯片，算力天花板就摆在那里。Klipper 的思路是换个工作模式：所有复杂计算交给上位机，主板只做脉冲输出和信号采集这类低层工作。打个比方，原来一个小超市既要收银、又要理货、还要盯监控，忙得手忙脚乱；现在改成总部做经营决策，门店只负责开门营业，效率自然不一样。上位机算力充足，就能跑更复杂的运动规划算法，能用更高的步进脉冲频率去驱动同样的电机，这些在入门板上用 Marlin 很难做到。
Klipper 带来的直接改变首先是加速度可以拉高。Marlin 下一般设 500-1000mm/s² 就觉得机器晃，Klipper 配合输入整形之后，2000-3000mm/s² 也很常见。对大多数打印任务来说，行程短的时候加速度提升带来的省时效果比单纯拉高速度上限更明显。其次是压力提前，它在换向和挤出启停时主动补偿喷嘴内熔体的残余压力，能明显减少拐角堆积、接缝起包这类问题。再有就是 Web 界面，浏览器里看打印进度、改配置、查日志，不用再拿 SD 卡来回搬运 G 代码和固件。
Klipper 还有一个容易被忽视的优点：配置热加载。Marlin 改一个参数要重新编译再刷写，来回折腾大半天；Klipper 改完配置执行一次配置文件保存，几十秒就能生效。这意味着调机痛感大幅下降——你面对的不是一个刷错只能重来的固件，而是一套可以随时改、随时看日志、随时回滚的软件系统。对于需要频繁尝试不同速度、加速度和回抽参数的玩家来说，这种迭代效率是决定性的。
| 对比维度 | Marlin 默认状态 | Klipper 升级后 |
|---|---|---|
| 运动计算位置 | 主板 | 上位机 |
| 常用加速度 | 500-1000mm/s² | 2000mm/s² 以上 |
| 改参数方式 | 重新编译刷写 | 修改配置并热加载 |
| 共振抑制 | 基本没有 | 输入整形 |
| 挤出补偿 | 简单回抽 | 压力提前 |
| 交互界面 | 屏幕 / 串口 | Web 界面 + 远程终端 |
1.2 你的 Ender-3S 到底能不能刷？硬件判断方法
先确认主板版本。Ender-3S 不同批次出现过好几种主板方案，比较常见的是 V4.2.2，也有 V4.2.7，更早的批次还有 8 位板方案。判断方法不复杂：断电拆开主板仓，看板子丝印。V4.2.2 的主控一般是 STM32F103，在 Klipper 支持列表里；如果是更老的 8 位方案，也能跑，只是内存比较紧张，输入整形效果多少会打折扣。另一个判断方式是主板上电后连电脑，在设备管理器里看串口芯片，CH340 或 CP2102 都意味着刷写路径非常成熟，遇到问题也容易找到资料。
还有一个容易忽略的点：屏幕。Ender-3S 原厂带的往往是 12864 LCD，部分批次配的是触摸屏。Klipper 对 12864 的支持很好，刷完能正常显示；但触摸屏基本会失效，因为它依赖 Marlin 专用的显示协议，Klipper 不兼容。这不影响主要使用，因为 Klipper 的主力交互是网页端，屏幕在刷机后更多是显示状态信息。如果你特别依赖机器面板上的实体按键操作，比如不打电脑就要调平、移轴，刷之前要有心理准备，要么接受屏幕功能受限，要么以后多开电脑或手机连网页。
1.3 收益边界在哪里，风险有哪些
Klipper 不是万能药。如果这台 Ender-3S 本身结构已经松垮，皮带老化、滑块有旷量，那刷完之后高速打印只会把机械问题放大，出来的表面甚至可能比 Marlin 时期还差。建议先检查 X/Y 皮带张紧度、热床固定螺丝和底座四角，把基础机械状态调整到位再刷固件。
另一个风险在于系统复杂度。Klipper 由上位机、主板固件、配置文件三部分组成，任何一环出问题都会导致整机罢工。原厂 Marlin 是开机即用；Klipper 需要上位机和打印机始终连接，上位机断电，机器跟着停工。如果你只想要一个“装完就不管”的稳定设备，Klipper 的上手门槛可能让你烦躁；如果你愿意花一两个晚上折腾，它给你的回报会远超固件本身带来的性能提升。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 升级前的物料准备与上位机环境搭建
2.1 上位机选型：树莓派、旧电脑与虚拟机怎么选
上位机是 Klipper 的大脑，它的核心要求是：能常开、有 USB 口、支持 Linux 系统。最常见的选择是树莓派，3B+ 跑 Klipper 已经非常流畅，没必要为了提高配置去追高价版本。树莓派 4B 的余量更大，可以顺便跑流体切片服务、监控摄像头这类附加功能。手上如果有淘汰的笔记本或迷你主机，一样能胜任，性能反而更强，缺点是功耗和体积偏大。我见过有人用旧笔记本刷 Debian 跑 Klipper 小半年，稳定性和速度都不输树莓派。
虚拟机方案我不推荐作为主力。原因是 USB 串口透传的实时性受宿主机调度影响，偶尔会丢包，打印过程中突然断连的体验非常糟糕。虚拟机拿来临时测试配置、熟悉命令可以，真正常打还是单独准备一台硬件更省心。三种方式的取舍可以参考这张表：
| 方案 | 硬件成本 | 上手难度 | 稳定性 |
|---|---|---|---|
| 树莓派 4B / 3B+ | 中等 | 低 | 高 |
| 旧笔记本 / 迷你主机 | 低 | 中 | 很高 |
| 虚拟机方式 | 最低 | 中 | 一般 |
2.2 系统镜像安装与远程连接细节
主流的做法是在上位机上安装带网页界面的打包镜像，常见的是 Mainsail OS 和 FluiddPi。它们的底层都是 Linux 系统加 Klipper 和配套服务，只是前端风格不同。Mainsail 的界面更整合，按钮命名接近日常用语，适合新手；Fluidd 更轻更快，适合喜欢精简界面的玩家。二者选哪个都不会错，我通常建议新手用 Mainsail。
安装分三步：先用系统镜像工具把镜像写到至少 32G 的 TF 卡里，然后把卡插入上位机，接好网线或配置好无线网络，上电等两三分钟。接着到路由器后台找到上位机的 IP，浏览器访问这个地址就能进入网页界面。首次登录的账号密码由镜像预设，官方说明页都会标注，登进去第一件事就是改密码，这个步骤别偷懒跳过。之后上传配置文件、查看日志、发送 G 代码都可以在网页里完成；需要跑命令行时，直接在界面上打开终端，或者用 SSH 登录。
这里有个经验：镜像烧录完成后先不要急着接打印机，先确认上位机系统能正常启动、网页界面能打开，再进入下一步。如果网页都打不开，先查网线、网段和密码，不要一路折腾到打印机那边，否则排查问题时变量太多，很难定位。
2.3 用 USB 识别串口，排除连接障眼法
在给主板刷 Klipper 之前，先把上位机和打印机主板用 USB 线连起来。这里有个容易踩的坑：USB 线必须是带数据功能的数据线，不是随便找一根充电线。判断方法很简单，连上后在终端里执行：
bash复制lsusb
如果能看到一个 CH340、CP210x 或者 STM32 相关的设备，说明数据链路通；如果什么都看不到，先换线，再换 USB 口，不要一上来就怀疑主板坏了。
另外，建议在插线时先让主板上电，再插入 USB 线。两边都处于通电状态时，瞬间电平差异有极小概率给串口芯片带来冲击；养成断电插拔的习惯，能省掉很多玄学问题。现在很多上位机系统已经包含串口驱动，如果你的系统里没驱动，联网更新一下内核模块就能解决。
3. 主板端固件编译与刷写
3.1 编译参数如何选才不出错
Klipper 的固件编译不像 Marlin 那样要调整大量功能开关，核心就几个关键项。通过 SSH 登录到上位机后，进入 Klipper 源码目录：
bash复制cd ~/klipper
make menuconfig
以常见的 V4.2.2 主板为例，基本配置是：
- Microcontroller:
STM32F103 - Bootloader offset:
8KiB bootloader或28KiB bootloader - Communication interface:
USB
Bootloader offset 是很多人反复刷不成功的根本原因。不同批次的主板出厂引导区尺寸可能不同，只能一一排查。建议第一次先试 8KiB，刷完如果主板无法识别，再换 28KiB，重新编译、重新刷卡，整个过程不超过五分钟。有人还会遇到兼容芯片的问题，比如丝印显示 GD32F103 但实际可当 STM32F103 用，选型时同样选 STM32F103 即可。
确认配置后保存退出，执行：
bash复制make
编译输出的固件位于 ~/klipper/out/klipper.bin。如果中途报错，执行 make clean 之后再重新配置编译，不必反复纠结目录状态。
3.2 给主板写入固件，SD 卡方式怎么操作
Ender-3S 大多数批次的主板都支持把固件放到 TF 卡里刷写。先把 TF 卡格式化成 FAT32，把刚才编译得到的 klipper.bin 重命名为 firmware.bin 放进去，断电插入前面板的 TF 卡槽，然后给打印机上电。屏幕会先亮，随后可能黑屏重启两次，这是正常现象，说明 Klipper 固件正在被加载。等十几秒屏幕稳定后，拔掉 TF 卡，把卡里的固件文件删除，避免下次开机误刷。
如果你的主板正好是老批次，这种刷写方式不适用，就要借助 ST-Link 或串口烧录工具。ST-Link 看着麻烦，流程其实不复杂：接好 SWD 四根线，用电脑上的烧录软件把 out/klipper.bin 写进去；纯串口方式则需要把主板切换到 ISP 模式，具体方法因主板而异，建议先查同类主板的操作案例，不要硬猜跳线位置。
有一点值得说：很多人在刷完固件后看屏幕黑屏或重复重启就以为是刷坏了，其实这恰恰表示成功。Klipper 固件没有原厂界面，上位机没启动、配置不正确时，屏幕就只能停在初始启动状态。这个判断意识能帮你省掉大量无用操作。
3.3 第一次连接：让 Klipper 找到主板
主板刷完 Klipper，上位机还不知道该访问哪个设备。先在终端执行：
bash复制ls /dev/serial/by-id/*
正常会看到类似 usb-Klipper_stm32f103xxxx 的符号链接。把这个完整路径记下来，因为后面要写到 printer.cfg 里。优先使用 /dev/serial/by-id 下的路径，不要直接写 /dev/ttyUSB0。tty 编号会随 USB 口插入顺序改变，而 by-id 对应的符号链接是稳定的，即使换了插口也基本不变。
然后在 Web 界面重启 Klipper 服务，或者执行：
bash复制systemctl restart klipper
再观察控制台输出。如果提示 Can not open /dev/serial/...，多半是串口路径不对，也可能是当前用户缺少串口访问权限。把当前用户加入 dialout 组：
bash复制sudo usermod -aG dialout $USER
重新登录或者重启会话，问题通常会消失。如果仍无法连接，就要考虑主板 Bootloader offset 选错，回到 3.1 重新编译配一把。
4. 打印机参数校准：从运动轴到热端的精细调整
4.1 rotation_distance 到底怎么算，常见参数参照
新版 Klipper 配置中，电机移动量的核心参数是 rotation_distance，意思是电机轴每转一圈，运动部件实际前进多少毫米。很多从 Marlin 转过来的用户习惯找“每毫米步数”，但 Klipper 推荐的方向是直接算机械传动关系。
Ender-3 系列 X 轴和 Y 轴常用 20 齿 GT2 带轮，GT2 带齿距 2mm，电机转一圈就是 20 × 2 = 40mm。如果你的机器换成 16 齿带轮，那就是 16 × 2 = 32mm。Z 轴常见 T8 丝杠，导程 8mm，旋转距离就是 8。挤出机不一样，挤出机型号、驱动轮直径和减速比共同决定了数值，远程送料挤出机的取值通常比直驱机型大。
| 轴 | 常见机械结构 | 经验旋转距离 |
|---|---|---|
| X | GT2 20齿带轮 | 40mm |
| Y | GT2 20齿带轮 | 40mm |
| Z | T8丝杠 | 8mm |
| E | 远程挤出机（按型号） | 常见 22-45mm |
不建议直接照抄网上的数字，因为一旦换过带轮齿数或者丝杠导程，数值就变了，跟着本机结构算一遍才靠谱。对于挤出机的准确校准，用实测法更稳妥。先把配置文件里的挤出机 rotation_distance 设一个估算值，加热到正常打印温度，拆下喷嘴侧挤出管，在挤出机入口外侧的耗材上做一个记号，命令挤出 100mm：
text复制G91
G1 E100 F60
G90
再量一次耗材实际前进距离。如果实际只挤出 95mm，原来设的是 20，那么修正为 20 × 100 / 95 ≈ 21.05。这个校准要在其他尺寸校准之前做，因为挤出流量不准会直接影响后续一切测量。
4.2 温度传感器类型与 PID 校准
Ender-3S 的原厂喷头和热床传感器几乎都是 100K NTC 热敏电阻，对应配置文件直接用官方模板里的 [thermistor] 定义就行。温度传感器这地方不要乱替换，你换了一种传感器却不改配置，温度读数偏几十度不是开玩笑，高温状态下还可能引发危险。
温度稳定性方面，需要做 PID。在 Web 控制台依次执行：
text复制PID_CALIBRATE HEATER=extruder TARGET=200
PID_CALIBRATE HEATER=heater_bed TARGET=60
每次校准会跑五六个加热周期，完成后会提示是否写入配置，选保存。PID 校准的意义是让加热管以合适的占空比维持目标温度，而不是满功率断续加热。校准之后，实际温度波动通常能稳定在 ±0.5℃ 以内。
还有一个不少玩家忽视的安全机制：verify_heater。Klipper 默认会监控升温速度，如果升温过慢会触发急停保护。天冷或者电源电压偏低时，你可能会看到类似加热异常的提示，这时优先检查加热管功率、供电电压和接线端子，不要图省事直接把保护参数调低。
4.3 归位、限位与行程保护
Ender-3S 原厂用三个机械限位开关，对应 X、Y、Z 轴。在 Klipper 配置里要分别设置 endstop_pin，并且指定归位方向，默认三个轴都是向最小位置归位。如果换过限位开关，或者用 BLTouch 替代了 Z 限位，对应的引脚必须改掉，否则一按归位就可能撞机。
Klipper 的引脚名有一个容易出错的地方：! 符号代表反转限位逻辑。机械限位开关是常开还是常闭会直接决定这里要不要加 !。调试时可以在控制台执行 QUERY_ENDSTOPS，手动按一下限位开关，看反馈是否正确变化。如果反馈反了，就把对应引脚加上或删掉 ! 再试。
如果你给机器加装 BLTouch，建议配置好 [bltouch] 之后先执行 QUERY_PROBE，确认探针下落和触点反馈正常，再启用自动调平。没有机械 Z 限位的情况下，务必设置 safe_z_home 或 homing_override，让机器先移动到热床安全坐标，再让探针下降，不然探针可能在热床边缘或模型外触发，结果很糟心。行程保护方面，max_z_position 要根据实际 Z 轴高度留出余量，防止喷头撞到顶架。
5. 输入整形与压力提前：性能调优实战
5.1 输入整形：为什么加速度能拉高还不振
输入整形听着抽象，放到实际场景里就很直观。每台打印机在特定加速度下都会按某个固有频率振动，反映在打印表面就是与移动方向垂直的振纹，人云亦云叫“鬼影”或“振铃波纹”。输入整形算法会在运动指令上叠加一个方向相反的补偿信号，把这个振动频率抵消掉，就像荡秋千时找准节奏顺势推一把，而不是乱使劲。配置好之后，机器可以用更高的加速度打印，表面却看不到明显的振纹。
Klipper 支持用加速度计来测共振，比如 ADXL345 这类传感器，接在打印头支架上，然后在控制台执行：
text复制TEST_RESONANCES AXIS=X
TEST_RESONANCES AXIS=Y
Klipper 会自动扫描频率范围并生成共振图谱。之后执行 SHAPER_CALIBRATE，它会根据采集到的数据推荐一个整形器类型和频率参数。
text复制SHAPER_CALIBRATE
完成之后生成类似这样的配置：
ini复制[input_shaper]
shaper_type_x = mzv
shaper_freq_x = 38.6
shaper_type_y = ei
shaper_freq_y = 41.2
保存配置时，Klipper 会把新参数追加到配置文件的底部，不要手动把这个区块挪来挪去，重复加载容易冲突。如果暂时没有加速度计，也可以通过打印特定的校准模型，根据振纹间距手工反推共振频率，效果稍差，但比完全没有方向要强得多。我的建议是，如果你打算长期玩 Klipper，加速度计值得投入，它能把调机从看手感变成看数据。
5.2 压力提前：让挤出动作跟得上喷嘴移动
压力提前解决的是另一类问题：挤出电机停止后，喷嘴内熔体仍有残余压力，还会继续挤出来一点，结果拐角堆积、接缝处起小包。Klipper 会在减速阶段提前反向补偿一点挤出量，抵消这个惯性残留。校准思路是打印一块高速单层方形，观察四个角的堆积情况。外角明显起包，说明压力提前值偏大；内角缺损或拉丝，说明值偏小。
具体做法：先把 pressure_advance 设为 0，然后用较高的速度和加速度（比如 100mm/s、3000mm/s²）打印一个边长 20-30mm 的单层方形。打印过程中可以直接用命令面板调整，Klipper 支持实时的压力提前参数覆盖：
text复制SET_PRESSURE_ADVANCE ADVANCE=0.05
逐层往下看，看到哪一段的转角最干净，就用那个数值写回配置。PLA 的常见区间在 0.03-0.10 之间，ABS、PETG 会略有不同；关键是挤出机类型差异很大，直驱通常在 0.02-0.06 附近，远程送料挤出机因为喉管反馈路径长，数值往往要更大。
5.3 日常提速的推荐组合与实操步骤
输入整形和压力提前都调好之后，就到了最让人兴奋的环节——提速。我在实践中得到一套比较稳妥的 Ender-3S 组合：普通速度 80-100mm/s，加速度 2000mm/s² 起步；模型结构简单、细节少、机械状态也比较好的时候，可以试到 3000mm/s²。这个幅度比 Marlin 原厂默认的 500mm/s² 带来的体验提升是大跨度的，也是大多数人升级 Klipper 之后最能感知的部分。
如果你的目标是极限速度，不建议一步到位，先把速度和加速度分别在切片软件里分档，每档用一个小立方体来试。测试模型可以设置：壁数 2、填充密度 20%，重点关注外表面振纹、转角处堆积和总打印时间。如果出现明显的表面瑕疵，记下当时的加速度，回配置里降低 15%-20% 再去测试。跑激进参数时，尽量先在小件上试，不要一上来就用大模型满载跑，防甩料防共振都得靠循序渐进的测试来兜底。
6. 常见问题排查与避坑经验
6.1 主板刷写后无法识别？换个思路很快解决
刷完固件，上位机 ls /dev/serial/by-id 看不到设备，最常见的两个原因是 Bootloader offset 选错和 SD 卡文件名不规范。先回编译目录里改 offset，重新编译再刷一次；如果还是没反应，把 TF 卡重格式化为 FAT32，确认文件名是 firmware.bin，部分主板只认全小写文件名。还有一种情况是卡里有旧固件残留，刷写时引导程序可能加载了旧文件，导致总是一个结果。记住一个规律：刷完拔卡再开机，如果提示变成了“无固件可运行”或者屏幕黑屏稳定，那往往是刷写成功但配置不对，不要反复重刷。
如果是老批次主板用 ST-Link 刷写，常见错误是连接超时，绝大多数是因为 SWD 引脚没接好或者目标板没单独供电。检查一下主机端是否欠压，再重新插拔接线，这类问题基本都是物理接触。
6.2 归位异常，先查限位逻辑再查硬件
刷完 Klipper 后按归位，机器要么不动作，要么直接朝某个方向猛冲。先别看机械，打开控制台发 QUERY_ENDSTOPS，手动按下对应限位开关，观察反馈值是否变化。反馈一直不变，说明引脚号写错或线断了；反馈变化的方向跟预期相反，说明需要增删 ! 取反符号。这个流程能快速区分问题出在配置还是接线。
如果归位过程会先向下扎，再看配置里是不是有 Z 轴优先归位逻辑或者 safe_z_home 设置遗漏。归位顺序错误在换过 BLTouch 的机器上尤其常见，一旦 Z 探针先触床而 X/Y 没归位，探针可能压到热床边缘甚至爆针，这类隐患要提前排掉。
6.3 打印质量异常：振纹、层纹、接缝崩线怎么定位
输入整形调完之后依然有斜向振纹，大概率是 X/Y 两根皮带的固有频率不同，需要分别校 X 轴和 Y 轴，然后把综合数据交给 Klipper 重新计算。层纹不规则的优先级更高，先检查 Z 轴丝杠是否干净、皮带松紧是否一致、挤出机是否打滑，机械问题没解决之前调固件参数是事倍功半。
接缝崩线和表面粗糙的情况，优先看向回抽距离和压力提前值。回抽太小，喷嘴在非挤出路径上漏料；回抽太大，又会把熔体抽入冷却区域造成堵头。一个容易忽略的细节是：回抽距离和压力提前是相互影响的，两个参数一起改，改完分别打印测试件验证，不要同时大改多个变量，否则出了问题根本不知道是哪个参数引入的。
6.4 加热异常与安全保护，千万别只看配置
Klipper 默认支持 min_temp 和 max_temp 检查，温度超范围会触发安全停机。这是保护机制，出问题不要急着把阈值改大。Ender-3S 上常见的“温度读数为 0”多半是传感器线断或接口松；“室温读数固定不变”可能是传感器类型配置错误。遇到加热失控类提示，先断电，检查加热管接线、PID 参数和供电电压；确认硬件无误后重刷固件再试。
对自动断电模块这类加装件的处理也要上心，Klipper 配置里要确保紧急停止时能同时切断加热电源。你可以把 printer.cfg 中的电源控制部分单独测试，模拟一次断电确认执行顺序。安全无小事，任何调参之前先想清楚它会不会影响加热失控保护，这一条永远排在最前面。
7. 写在最后的实在提醒
升级 Klipper 不是一次性工程，它更像是给一辆老车换了新发动机，改完还要记得日常保养。我的习惯是每次换喷嘴、换热端、换皮带，或者大保养之后，重新跑一遍压力提前和输入整形校准，因为任何机械参数的改变都会让旧数据失效。刚开始接触 Klipper 的朋友，建议先花一个晚上把 printer.cfg 从头到尾读一遍，这个文件的注释写得比较清楚，很多问题不需要到处求助，看日志提示和注释就能定位。最后再分享一个我会长期坚持的习惯：每次刷固件或改配置前，先把当前配置文件复制一份备份，文件名带上日期后缀。这个动作一两分钟就能完成，但只要调乱过一次参数，你就能明白它有多香——一分钟回到可用状态，比任何花哨的备份方案都直接。祝刷机顺利，多打漂亮件。