PrintLink部署与运维
故障排查
打不出来、卡住、打错格式时按什么顺序查：从连接、授权、打印机到参数与日志。
最后更新
按下面的顺序查，能覆盖绝大多数情况。每一步都给出「看什么」和「怎么处理」。
1. 连接通不通
看：页面能不能连上。
const probe = await PrintLink.detect();
console.log(probe.installed, probe.reachable, probe.reason);| 结果 | 处理 |
|---|---|
installed: false | PrintLink 没装或没启动，引导用户安装 / 启动 |
installed: true, reachable: false | 服务没跑起来，或端口不对——检查托盘状态与控制台「设置」里的端口 |
| 都正常 | 继续下一步 |
命令行快速确认：curl http://127.0.0.1:17888/healthz 返回 200 即服务正常。
2. 授权过了没有
看：错误码。
| 错误码 | 含义 | 处理 |
|---|---|---|
PAIRING_PENDING | 等用户在本机确认 | 提示用户，不要当故障 |
PAIRING_DENIED | 用户拒绝了 | 说明原因，提供重新申请入口 |
PERMISSION_DENIED | 缺权限 | 引导用户到控制台「安全与站点」为该站点补权限 |
TOKEN_INVALID | 令牌失效 | 重新 ensureAuthorized() |
ORIGIN_NOT_ALLOWED | 该来源被策略拒绝 | 检查「新站点策略」与受信任列表 |
3. 打印机在不在
const { queues } = await client.listPrinters();
const status = await client.printerStatus(queueId);| 现象 | 含义 | 处理 |
|---|---|---|
| 列表为空 | 系统里没有可用打印机 | 先让操作系统的打印功能正常 |
status.state: 'offline' | 打印机离线 | 检查电源、连接、是否被其他设备占用 |
status.reasons 里有缺纸 / 卡纸 / 门打开 | 硬件提示 | 就地处理后面板复位 |
一直是 printing 不动 | 队列卡住 | 到控制台「任务」页取消该任务，检查打印机面板 |
4. 参数是不是被降级了
先校验再提交，不要打完才发现参数不对：
const check = await client.compose({ queueId }).paper('A3').addPdf(bytes).validate();
console.log(check.requested); // 你要求的
console.log(check.effective); // 实际会用的
console.log(check.warnings); // 差异说明常见警告与含义见打印参数。
打印出来明显偏小、被裁切、位置不对时看图片位置与大小与纸张设置。 照片发白、颗粒重通常是没设对纸张类型。
5. 还是不对，导出日志包
日志包里记录了参数是怎么一步步定下来的、渲染与送打过程、打印机能力读取结果， 比错误码详细得多。见日志与日志包。
常见现象速查
| 现象 | 最可能的原因 |
|---|---|
| 网页能连上但打不出纸 | 权限不足，或打印机离线 |
| 提示需要授权，用户说点过同意了 | 确认是在同一台电脑上点的；确认站点没被暂停 |
| 局域网终端连不上 | 防火墙、来源白名单、或浏览器拦截了混合内容，见局域网打印工作站 |
| 打印了一份但打了两遍 | 用户连点，用幂等键避免，见打印 |
| 预览正常、实物版式不同 | 确认用的是同一次预览会话的打印入口（预览里的打印不会重新渲染） |
| 大量任务塞满队列 | 检查是不是在循环里调用了 print()，改用一次 compose() |
| 打印机队列里有别人的任务 | 用 getJob 确认任务归属；不要用清空队列来做取消 |
需要更多人介入时
- 记下错误码与发生时间；
- 按日志与日志包导出日志包；
- 日志包不含文档内容与令牌，可以按组织规定投递。