企业官网建设流程全解析

Klipper 调平全指南：从纸张测试到自动探针的床面校准实战

【免费下载链接】klipperKlipper is a 3d-printer firmware项目地址: https://gitcode.com/GitHub_Trending/kl/klipper

导读

床面调平（Bed Leveling，有时也称 "bed tramming"）是 Klipper 获得高质量打印件的关键前置步骤：床面未校准会直接导致首层附着不良、翘边（warping）以及贯穿整个打印过程的隐性缺陷。本文以 Klipper 官方文档 docs/Bed_Level.md 为骨架，系统讲解床面调平的目标与精度要求、最核心的"纸张测试"（paper test）操作流程，并结合仓库内 manual_probe.py、probe.py、bed_screws.py、screws_tilt_adjust.py 等源码揭示 TESTZ 二分逼近、探针校准与重复性验证等底层原理，帮助你掌握从手动调平到自动探针调平的完整实战方案。

调平的本质目标：精度 25 微米

理解调平目标比执行操作更重要。如果打印过程中给打印机下发了X0 Y0 Z10的指令，那么目标是让喷嘴距离床面恰好 10mm；当继续下发X50 Z10时，目标是在整段水平运动中喷嘴与床面的距离始终保持在 10mm。

Klipper 要求 Z 轴距离的校准精度达到约25 微米（0.025mm）以内。这是一个远小于人类头发直径的尺度，无法"用肉眼"测量，且热膨胀等细微效应都会影响该尺度下的测量。获得高精度的秘诀在于：使用可重复的过程，并借助打印机自身运动系统的高精度来完成调平。

第一步：选择合适的校准机制

不同结构的打印机采用不同的调平方法，但它们都最终依赖于下文描述的"纸张测试"。在运行任何校准工具之前，必须先完成 Config_checks.md 中描述的检查流程（验证温度、加热器、步进电机使能脚、限位开关、电机方向与运动等），确认基础运动正常后再进行床面调平。

按打印机类型选择对应文档：

• 配有"自动 Z 探针"的打印机：先按 Probe_Calibrate.md 校准探针；
• Delta 打印机：参见 Delta_Calibrate.md；
• 带床面调平螺丝与常规 Z 限位开关的打印机：参见 Manual_Level.md。

校准期间可能需要把 Z 轴的position_min设为负数（例如position_min = -2）。打印机即使在校准例程中也会强制执行边界检查，设置为负数允许喷嘴移动到标称床面位置之下，有助于确定床面的实际位置。这一点在源码中也有呼应：probe.py中的HINT_TIMEOUT提示明确指出——"如果探针移动距离不足而未触发，请考虑降低 Z 轴最小位置（Z 最小值可以为负）以便探针走得更远"。

核心操作：纸张测试（Paper Test）

纸张测试是 Klipper 最主要的床面校准机制：在喷嘴与床面之间放置一张普通复印纸，命令喷嘴下降到不同 Z 高度，直到来回推动纸张时感受到轻微摩擦。即使拥有自动 Z 探针也必须理解纸张测试——探针本身的校准恰恰依赖这个测试完成。

测试准备

1. 用剪刀裁一小块矩形纸（例如 5×3 cm）。纸张厚度通常约 100 微米（0.100mm），精确厚度并不重要。

2. 检查喷嘴与床面，确保没有塑料残留！若喷嘴上有塑料，先加热挤出机，用金属镊子清除，等挤出机完全冷却到室温再继续（冷却期间用镊子随时清除溢出的塑料）。

3. 必须在喷嘴与床面均为室温时进行纸张测试！喷嘴加热后，热膨胀会使喷嘴相对床面的位置发生变化，典型膨胀量约 100 微米，与一张纸的厚度相当。先在"两者相等"的假设下开始校准，后续再精确测定二者的差值（见下文"确定热膨胀量"一节）。

   为何不在热态校准？热态校准会把少量熔融塑料粘到纸上，改变摩擦手感，使校准更难做好；同时大幅增加烫伤风险。热膨胀量是稳定值，可轻易在校准后期被补偿。

4. 如果始终在某一种胶带或打印表面上打印，可以直接带着该表面做测试。但要注意胶带本身有厚度，不同胶带/打印表面会影响 Z 测量，每种在用的表面都应重新做一次纸张测试。

使用自动化工具确定精确 Z 高度

务必使用自动化工具来获取精确 Z 高度！Klipper 提供了多个辅助脚本：MANUAL_PROBE、Z_ENDSTOP_CALIBRATE、PROBE_CALIBRATE、DELTA_CALIBRATE，按上文"选择合适的校准机制"一节挑选即可。

在 OctoPrint 终端窗口运行相应命令，脚本会在终端输出中提示用户交互，类似：

Recv: // Starting manual Z probe. Use TESTZ to adjust position. Recv: // Finish with ACCEPT or ABORT command. Recv: // Z position: ?????? --> 5.000 <-- ??????

当前喷嘴高度（打印机当前理解的值）显示在--> <--之间；右侧数字是最后一次大于当前高度的探测尝试高度，左侧是最后一次小于当前高度的探测尝试高度（若尚未尝试则显示??????）。

TESTZ 命令：移动与二分

将纸放在喷嘴与床面之间（可折起纸的一角方便拿取，来回推纸时尽量不要向下压床面），然后用TESTZ命令让喷嘴向纸靠近：

TESTZ Z=-.1

TESTZ按相对距离移动喷嘴（Z=-.1即向床面靠近 0.1mm）。移动停止后，来回推纸感受摩擦，反复执行TESTZ直到感受到轻微摩擦。若摩擦过大，可用正值让喷嘴向上；也支持TESTZ Z=+或TESTZ Z=-做"二分"——移动到两次位置的中点。例如收到如下提示：

Recv: // Z position: 0.130 --> 0.230 <-- 0.280

执行TESTZ Z=-会把喷嘴移到 Z=0.180（0.130 与 0.230 的中点），可快速逼近一致的摩擦手感。Z=++与Z=--则直接回到过去某次测量位置——上例中TESTZ Z=--会把喷嘴移回 Z=0.130。

从源码看，TESTZ的二分与跳跃逻辑实现在 manual_probe.py 的cmd_TESTZ（第 255-283 行）：+/-取相邻历史位置的中点（同时受BISECT_MAX = 0.200mm 单步上限约束），++/--直接跳到相邻历史位置；每次测试的位置会插入有序列表past_positions，因此report_z_status总能给出上一/下一参考值。此外move_z中Z_BOB_MINIMUM = 0.500会在每次测试前先把喷嘴抬到目标高度以上 0.5mm 再下落，保证运动方向一致、减少背隙误差。

接受与中止

找到轻微摩擦后执行：

ACCEPT

即接受当前 Z 高度并继续对应的校准工具。摩擦的精确大小并不关键（与热膨胀量、纸张厚度一样），只需每次测试尽量保持相同的手感。若测试过程出错，用ABORT命令退出校准工具。

确定热膨胀量：微调 Z 偏移

完成调平后，可以进一步精确计算"热膨胀 + 纸张厚度 + 纸张测试摩擦量"的综合影响。这种计算通常并非必需——多数用户发现简单的纸张测试已足够，但需要时可按以下方法操作：

1. 打印一个四壁笔直的测试件，可使用 docs/prints/square.stl（大型空心方块）。
2. 切片时确保首层与后续层使用相同的层高和挤出宽度；使用较粗的层高（约为喷嘴直径的 75%），不要使用裙边（brim）或筏层（raft）。
3. 打印完成后等其冷却取下，检查最底层（也可用手指/指甲沿底边划过）。
4. 若底层沿四周轻微外鼓，说明喷嘴离床面偏近，可执行SET_GCODE_OFFSET Z=+.010抬升高度，在后续打印中继续观察调整。此类调整通常以 10 微米（0.010mm）为单位。
5. 若底层持续比后续层窄，则用SET_GCODE_OFFSET做负 Z 调整；拿不准时，先减小 Z 调整直到底层出现轻微外鼓，再回退到外鼓消失。

SET_GCODE_OFFSET的实现位于 gcode_move.py 的cmd_SET_GCODE_OFFSET（第 208-226 行）：它同时支持Z=<pos>（绝对偏移）与Z_ADJUST=<adjust>（在现有偏移上累加）两种参数，并可选MOVE=1立即移动喷嘴到新偏移位置。其语义在 G-Codes.md 中有详细说明：例如SET_GCODE_OFFSET Z=0.2后，后续 G-Code 的 Z 高度都会加上 0.2mm。

最稳妥的应用方式是在切片器中设置一个START_PRINTG-Code 宏，让切片器在每次打印开始时调用该宏，并在宏内加入SET_GCODE_OFFSET命令。详见 Slicers.md。

各调平工具的源码级解析

Z 限位开关校准：Z_ENDSTOP_CALIBRATE

对带独立 Z 轴的笛卡尔打印机，Manual_Level.md 建议先归零（home），把喷嘴移到床面上方至少 5mm 处并移动到床面中心附近，然后在终端运行：

Z_ENDSTOP_CALIBRATE

随后按"纸张测试"步骤确定该位置喷嘴与床面的实际距离，ACCEPT后执行SAVE_CONFIG把结果写回配置文件。其核心逻辑在 manual_probe.py 的z_endstop_finalize（第 96-107 行）：新position_endstop等于当前 position_endstop - 纸张测试得到的床面 Z 值，并通过configfile.set()暂存，等待SAVE_CONFIG写入。

工程建议：尽量把 Z 限位开关装在 Z 轴远离床面的一端（远离床面归零更稳健，Z 归零总是安全的）。若必须向床面方向归零，建议把限位开关调整到在床面上方约 0.5mm 处触发——几乎所有限位开关都能安全地被按压超过触发点一小段距离。此时Z_ENDSTOP_CALIBRATE会报告一个小的正值（约 0.5mm）position_endstop，可降低意外撞床的风险。物理开关位置合适后，后续微调都应在软件中完成（再次运行Z_ENDSTOP_CALIBRATE或直接改配置中的 Zposition_endstop）。

床面螺丝手动调整：BED_SCREWS_ADJUST

利用床面螺丝调平的诀窍是在调平过程中借助打印机的高精度运动系统：命令喷嘴移动到每颗螺丝附近，然后调整螺丝直到床面与喷嘴距离一致。Klipper 的[bed_screws]工具需要指定每颗螺丝的 XY 位置：

[bed_screws] screw1: 100, 50 screw2: 100, 150 screw3: 150, 100

若螺丝位于床面下方，则指定其正上方的 XY 位置；若螺丝在床面外，则指定床面范围内离螺丝最近的位置。改完配置后执行RESTART加载，然后运行：

BED_SCREWS_ADJUST

该工具会把喷嘴移到每颗螺丝的 XY 位置并下降到 Z=0，此时用"纸张测试"调整喷嘴正下方的床面螺丝（调整螺丝而非命令喷嘴移动），直到推纸有轻微摩擦。之后运行ACCEPT或ADJUSTED：

• ADJUSTED：螺丝需要明显调整时使用（通常超过约 1/8 圈），工具会额外安排一轮螺丝调整；
• ACCEPT：无需明显调整时使用；
• ABORT：提前退出工具。

工具在所有螺丝都验证为无需明显调整时才算成功完成。该方法最适合平面度好的打印面（如玻璃）与笔直导轨的打印机。

源码层面，bed_screws.py 的cmd_ACCEPT维护accepted_screws计数：全部螺丝ACCEPT后若配置了_fine_adjust坐标则进入精调阶段，否则输出 "Bed screws tool completed successfully" 结束。支持speed、probe_speed、horizontal_move_z、probe_height等配置参数。

三螺丝高精度精调：screwN_fine_adjust

若打印机使用三颗螺丝且全部位于床面下方，可进行第二阶段的"高精度"调平：命令喷嘴移动到床面因单颗螺丝调整而位移更大的位置。例如螺丝位于 A、B、C 三点时，调整 C 处螺丝会让床面沿 A、B 两点定义的摆线摆动（图中绿线），此时在 D 位置调整 C 螺丝可获得比 C 点直接调整更大的位移杠杆。

启用方法是在[bed_screws]中添加额外坐标：

[bed_screws] screw1: 100, 50 screw1_fine_adjust: 0, 0 screw2: 100, 150 screw2_fine_adjust: 300, 300 screw3: 150, 100 screw3_fine_adjust: 0, 100

启用后BED_SCREWS_ADJUST会先在每颗螺丝正上方做粗调，全部接受后再在附加位置做精调，每个位置继续使用ACCEPT/ADJUSTED。

用探针计算螺丝调整量：SCREWS_TILT_CALCULATE

这是另一种借助 Z 探针（BL Touch、电感传感器等）校准床面水平的方法。需要确定"探针位于螺丝正上方"时对应的喷嘴坐标并写入配置：

[screws_tilt_adjust] screw1: -5, 30 screw1_name: front left screw screw2: 155, 30 screw2_name: front right screw screw3: 155, 190 screw3_name: rear right screw screw4: -5, 190 screw4_name: rear left screw horizontal_move_z: 10. speed: 50. screw_thread: CW-M3

screw1始终是其他螺丝的参考基准，系统假定它高度正确。先运行G28归零，再运行SCREWS_TILT_CALCULATE，输出类似：

Send: G28 Recv: ok Send: SCREWS_TILT_CALCULATE Recv: // 01:20 means 1 full turn and 20 minutes, CW=clockwise, CCW=counter-clockwise Recv: // front left screw (base) : x=-5.0, y=30.0, z=2.48750 Recv: // front right screw : x=155.0, y=30.0, z=2.36000 : adjust CW 01:15 Recv: // rear right screw : y=155.0, y=190.0, z=2.71500 : adjust CCW 00:50 Recv: // read left screw : x=-5.0, y=190.0, z=2.47250 : adjust CW 00:02 Recv: ok

含义解读：

• front left screw 是参考点，不要改动它；
• front right screw 需顺时针转动 1 整圈又 1/4 圈（CW 01:15）；
• rear right screw 需逆时针转动 50 分钟（CCW 00:50）；
• rear left screw 需顺时针转动 2 分钟（CW 00:02，可忽略）。

注意这里的"分钟"指钟表表盘的分钟：15 分钟即 1/4 圈。反复执行直到床面水平良好——通常以所有调整量低于 6 分钟为标准。

若探针装在热端侧面（带 X/Y 偏移），请注意：调整床面倾斜会使之前在有倾斜床面上做的探针校准失效，务必在调整完螺丝后重新运行 Probe_Calibrate.md。

MAX_DEVIATION 参数：配合已保存的床面网格（bed mesh）使用，用于确保床面水平没有偏离创建网格时的状态太远。例如把SCREWS_TILT_CALCULATE MAX_DEVIATION=0.01加入切片器自定义启动 G-Code（在加载网格之前）：若偏差超过限制（此处 0.01mm）将中止打印，给用户调整螺丝并重新打印的机会。对应实现在 screws_tilt_adjust.py 的probe_finalize（第 123-127 行）：任一螺丝与基准的偏差超过MAX_DEVIATION时抛出 "bed level exceeds configured limits" 错误。

DIRECTION 参数：当调平螺丝只能单向转动时使用。例如螺丝起始于最低（或最高）位置、只能单向转动来抬高（或降低）床面：只能顺时针转则运行SCREWS_TILT_CALCULATE DIRECTION=CW，只能逆时针则用DIRECTION=CCW。工具会选择合适的参考点，使所有螺丝都能朝给定方向转动来完成调平。源码中该逻辑位于probe_finalize（第 76-85 行）：有方向约束时以最高/最低螺丝为基准，从而保证调整方向一致。

自动探针校准与精度验证

探针 X/Y 偏移校准

对配置了[probe]或[bltouch]的打印机，先归零并把喷嘴移到床面中心附近，在探针下方贴一块美纹胶带；在终端执行PROBE，在胶带上探针正下方做标记；用GET_POSITION记录工具头 XY（例如X:46.5 Y:27），再用一系列G1命令把喷嘴移到标记正上方并用GET_POSITION记录喷嘴位置。则：

x_offset = 喷嘴X - 探针X y_offset = 喷嘴Y - 探针Y

把值写入 printer.cfg，移除胶带，RESTART生效。PROBE与GET_POSITION的输出格式可对照 G-Codes.md。

探针 Z 偏移校准：PROBE_CALIBRATE

z_offset是探针触发时喷嘴与床面的距离，对高质量打印至关重要。运行：

PROBE_CALIBRATE

工具会先自动探测一次，然后抬升喷嘴、移动到探测点上方的喷嘴位置并启动手动探针——若喷嘴没有移到自动探测点上方，先ABORT并重新校准 XY 偏移。手动探针启动后按"纸张测试"确定实际距离，ACCEPT后用SAVE_CONFIG保存。

源码中 probe.py 的cmd_PROBE_CALIBRATE（第 107-123 行）先执行run_single_probe获得探针触发位置，再抬升 5mm 并把喷嘴移动到ppos.bed_x/bed_y，最后启动ManualProbeHelper；probe_calibrate_finalize（第 94-105 行）按公式z_offset = 原z_offset - 纸张测试床面Z + 探针触发床面Z计算并暂存新值。

失效条件：改动打印机运动系统、热端位置或探针位置都会使PROBE_CALIBRATE结果失效；探针带 X/Y 偏移时，任何床面倾斜调整（调螺丝、DELTA_CALIBRATE、Z_TILT_ADJUST、QUAD_GANTRY_LEVEL等）同样使其失效，之后必须重新校准。一旦PROBE_CALIBRATE失效，之前用探针获得的 Bed_Mesh.md 结果也随之失效，需要在校准探针后重跑BED_MESH_CALIBRATE。

探针重复性检查：PROBE_ACCURACY

校准完成后建议验证探针的可重复性：归零、移到床面中心附近，运行PROBE_ACCURACY。命令默认探测 10 次，输出类似：

Recv: // probe accuracy: at X:0.000 Y:0.000 Z:10.000 Recv: // and read 10 times with speed of 5 mm/s Recv: // probe at -0.003,0.005 is z=2.506948 ... Recv: // probe accuracy results: maximum 2.519448, minimum 2.506948, range 0.012500, average 2.513198, median 2.513198, standard deviation 0.006250

判定标准：

• 理想情况最大值与最小值完全相同；正常情况二者相差一个 Z "步距"（step distance）或最多 5 微米（0.005mm）。步距 =rotation_distance / (full_steps_per_rotation × microsteps)。上例中 Z 步距为 0.0125，因此 range 0.012500 属正常。
• 若 range 大于 25 微米（0.025mm），探针精度不足以支撑常规调平流程。可尝试调整探针速度（PROBE_SPEED）与探测起始高度来改善，PROBE_ACCURACY支持用不同参数反复测试，详见 G-Codes.md。若探针总体可重复但偶有离群值，可通过 Config_Reference.md 中的samples参数让每次探测多次采样取均值/中位数来抵消。
• 修改probe_speed、samples等设置后需RESTART，并建议重新校准z_offset。
• 如果始终无法获得可重复结果，就不要用该探针做床面调平——Klipper 提供了多种手动探测工具（见本文与 Manual_Level.md）可以替代。

从源码看，PROBE_ACCURACY的统计实现在 probe.py 的cmd_PROBE_ACCURACY（第 125-169 行）：探测SAMPLES次（默认 10）后计算最大值、最小值、range、平均值、中位数与标准差；多采样平均由SampleAveragingHelper.run_probe（第 374-403 行）与calc_probe_z_average（第 17-31 行，支持average/median两种方式）完成，samples_tolerance与samples_tolerance_retries负责异常样本的重试判定。

位置偏差与温度偏差检查

部分探针存在系统性位置偏差（例如探针支架沿 Y 轴移动时轻微倾斜，导致不同 Y 位置结果偏移），这在 Delta 打印机上较常见，但所有打印机都可能出现。用PROBE_CALIBRATE在不同 XY 位置测量z_offset：Delta 打印机在 A/B/C 塔附近各测一次，笛卡尔/CoreXY 打印机在床面四角附近测量。若最小与最大z_offset之差超过 25 微米（0.025mm），该探针不适合常规调平流程。

温度也会造成系统性偏差（探针温度更高时可能一致地在更低高度触发）。建议在一致的温度下运行调平工具：要么始终在室温下运行，要么始终在达到稳定打印温度后运行；无论哪种，都应在达到目标温度后等待几分钟让机器整体温度一致。检查方法是：室温下归零、移到床面中心运行PROBE_ACCURACY记录结果；不重新归零、不断开步进电机使能的情况下把喷嘴和床加热到打印温度再运行一次，理想情况两次结果一致。

补充建议与文档地图

• 使用 Trinamic 步进驱动时，可启用 Endstop_Phase.md 的限位相位检测来提高开关触发精度，从而提升 Z 限位校准质量。
• 所有校准命令的完整参数（MANUAL_PROBE [SPEED=<speed>]、TESTZ Z=<value>等）见 G-Codes.md；[bed_screws]、[screws_tilt_adjust]、[probe]的完整配置项（speed、probe_speed、horizontal_move_z、probe_height、samples、sample_retract_dist、screw_thread等）见 Config_Reference.md。
• 床面网格补偿（保存/加载网格、BED_MESH_CALIBRATE）见 Bed_Mesh.md；Delta 专用校准见 Delta_Calibrate.md。

总体而言，Klipper 的调平体系遵循"纸张测试建立基准 → 手动/探针工具接力校准 → 探针精度与偏差验证 → 打印测试件微调 Z 偏移"的完整链路。无论使用哪种调平机制，保持过程可重复、温度一致，并善用TESTZ的二分逼近与各工具的ACCEPT/ADJUSTED流程，就能稳定地把 Z 距离精度收敛到 25 微米量级，为首层质量打下坚实基础。

【免费下载链接】klipperKlipper is a 3d-printer firmware项目地址: https://gitcode.com/GitHub_Trending/kl/klipper