簡(jiǎn)介SilentPrint 是一款專為網(wǎng)頁靜默打印設(shè)計(jì)的 JavaScript 中間件面向需要無交互自動(dòng)打印場(chǎng)景的 Web 開發(fā)者可應(yīng)用于發(fā)票收據(jù)、報(bào)表合同及自助服務(wù)終端等場(chǎng)景。壓縮包共 44 個(gè)文件以 22 個(gè) JS 腳本和 3 個(gè) Vue 組件為核心另含 HTML 頁面、Markdown 文檔、YAML 配置、ESLint 規(guī)則及圖標(biāo)等整體僅 154KB輕量且模塊劃分清晰。通過示例工程可系統(tǒng)學(xué)習(xí)靜默打印的完整實(shí)現(xiàn)鏈路利用 CSS 媒體查詢調(diào)整打印樣式結(jié)合 HTML2Canvas 將頁面渲染為圖片后發(fā)送至打印機(jī)并借助 Web Worker 在后臺(tái)執(zhí)行打印任務(wù)以避免阻塞主線程。項(xiàng)目基于 Electron-Vue 搭建包含主進(jìn)程與渲染進(jìn)程通信、webpack 多環(huán)境配置和演示頁面能幫助開發(fā)者理解打印流程控制、瀏覽器兼容性處理及降級(jí)方案。目前已有 5277 人學(xué)習(xí)下載適合具有一定前端基礎(chǔ)、希望為 Web 應(yīng)用快速接入后臺(tái)打印能力的開發(fā)者參考。1. SilentPrint 是干什么的把「選打印機(jī)、調(diào)參數(shù)、點(diǎn)確定」這三步從網(wǎng)頁里去掉窗口辦事、倉(cāng)庫(kù)開單、藥房貼簽這類場(chǎng)景里每天都會(huì)重復(fù)一個(gè)動(dòng)作打開網(wǎng)頁上的單據(jù)點(diǎn)打印瀏覽器彈出一個(gè)打印預(yù)覽框再選一次打印機(jī)、核對(duì)紙張方向、調(diào)頁邊距最后點(diǎn)確定。一套動(dòng)作五六次點(diǎn)擊一天重復(fù)上百次手快的人也會(huì)煩。SilentPrint 要解決的就是這件事——它是一個(gè)常駐本機(jī)的中間件網(wǎng)頁通過 HTTP 接口把打印任務(wù)丟給它它直接把內(nèi)容送進(jìn)打印機(jī)隊(duì)列全程不彈預(yù)覽、不出對(duì)話框、不需要人工介入。對(duì)網(wǎng)頁前端來說靜默打印從一個(gè)「瀏覽器不允許的事」變成了「一次普通請(qǐng)求」。這篇文章會(huì)從鏈路設(shè)計(jì)、最小實(shí)現(xiàn)、參數(shù)調(diào)優(yōu)到高頻踩坑點(diǎn)講透適合那些已經(jīng)有網(wǎng)頁管理系統(tǒng)、不想改造業(yè)務(wù)流程只想讓單據(jù)能直接出紙的開發(fā)者和實(shí)施人員。2. 靜默打印鏈路拆解瀏覽器為什么不肯靜默中間件怎么接住2.1 瀏覽器打印的沙箱邊界不是做不到是不允許先回答一個(gè)很多人問過的問題為什么網(wǎng)頁不能直接調(diào)用系統(tǒng)打印隨便打開一個(gè)網(wǎng)頁的控制臺(tái)輸入print()就知道瀏覽器只提供了window.print()這個(gè)入口而它的行為是「彈出打印對(duì)話框」沒有任何參數(shù)能讓它跳過對(duì)話框直接出紙。這不是瀏覽器偷懶而是安全模型故意這樣設(shè)計(jì)的。網(wǎng)頁運(yùn)行在沙箱里不能直接訪問文件系統(tǒng)、不能調(diào)系統(tǒng) API、也不能感知本機(jī)裝了什么打印機(jī)。如果允許一個(gè)陌生網(wǎng)頁直接往打印機(jī)塞任務(wù)那廣告頁面完全可以循環(huán)打印上千張紙把公司耗材打光甚至配合驅(qū)動(dòng)漏洞做更危險(xiǎn)的事。所以「靜默打印」這個(gè)需求本質(zhì)上是在和瀏覽器的安全邊界對(duì)著干硬用純前端方案繞不過去。我在早期做過一次嘗試用隱藏的 iframe 加載內(nèi)容再調(diào)print()結(jié)果打印對(duì)話框照樣彈出來而且 iframe 里的樣式還經(jīng)常丟。后來又試過 ActiveX 控件、瀏覽器插件要么只能在特定內(nèi)核里跑要么每次升級(jí)瀏覽器就失效。最后穩(wěn)定下來的方案就是現(xiàn)在大家普遍采用的做法在瀏覽器之外放一個(gè)本地中間件它不依賴網(wǎng)頁權(quán)限由操作系統(tǒng)直接授權(quán)去調(diào)用打印能力。這套鏈路拆開看是三層。第一層是網(wǎng)頁端負(fù)責(zé)把要打印的內(nèi)容準(zhǔn)備好發(fā)一個(gè) HTTP 請(qǐng)求第二層是中間件跑在用戶的電腦或打印服務(wù)器上接收請(qǐng)求、校驗(yàn)參數(shù)、調(diào)系統(tǒng)打印命令第三層是打印機(jī)驅(qū)動(dòng)和假脫機(jī)服務(wù)把任務(wù)真正輸出到紙張上。網(wǎng)頁只在第一層中間件隔斷了瀏覽器安全策略和操作系統(tǒng)打印接口之間的沖突。2.2 中間件在鏈路里的角色只做四件事別讓它背更多包袱SilentPrint 中間件的職責(zé)邊界是我在實(shí)際項(xiàng)目里反復(fù)調(diào)整后定下來的。它只做四件事提供 HTTP 服務(wù)、校驗(yàn)打印參數(shù)、調(diào)用系統(tǒng)打印接口、把任務(wù)狀態(tài)回傳。任何超出這四件事的功能都不應(yīng)該塞進(jìn)中間件里。這個(gè)邊界很重要。常見的反面教材是把模板渲染也塞進(jìn)中間件——讓中間件去數(shù)據(jù)庫(kù)取數(shù)據(jù)、套模板、生成單據(jù)?？雌饋硎×艘淮?HTTP 請(qǐng)求但中間件開始依賴業(yè)務(wù)系統(tǒng)升級(jí)業(yè)務(wù)時(shí)還得同步升級(jí)打印端現(xiàn)場(chǎng)實(shí)施的人會(huì)瘋掉。我一般會(huì)把「生成內(nèi)容」和「打印內(nèi)容」嚴(yán)格分開網(wǎng)頁負(fù)責(zé)把 HTML 或 PDF 內(nèi)容算好中間件只負(fù)責(zé)把它打出來。另一個(gè)容易越界的點(diǎn)是權(quán)限管理。有人希望中間件自己管用戶權(quán)限誰有權(quán)限打印、誰沒有。這個(gè)我也不建議做。權(quán)限應(yīng)該在業(yè)務(wù)系統(tǒng)里控制中間件只認(rèn)識(shí)業(yè)務(wù)系統(tǒng)下發(fā)的任務(wù)不認(rèn)識(shí)具體操作人。它就像一個(gè)打印機(jī)代理任何可以訪問它的服務(wù)都能提交任務(wù)安全邊界靠「誰能訪問這個(gè)端口」來控制而不是在中間件里再寫一套用戶體系。系統(tǒng)的差異也應(yīng)該收在中間件內(nèi)部。Windows、Linux、macOS 的打印命令完全不同但網(wǎng)頁端不需要知道這些。前端只需要POST一個(gè) JSON中間件根據(jù)運(yùn)行平臺(tái)決定調(diào)lp還是系統(tǒng)打印接口。這個(gè)「差異隔離」是中間件存在的最重要價(jià)值比省幾次點(diǎn)擊更關(guān)鍵。2.3 先定協(xié)議SilentPrint 的四個(gè)核心接口寫代碼前我習(xí)慣先把接口協(xié)議定下來。SilentPrint 的協(xié)議設(shè)計(jì)遵循「請(qǐng)求要簡(jiǎn)單、響應(yīng)要明確」的原則網(wǎng)頁端只關(guān)心任務(wù)有沒有被接收中間件負(fù)責(zé)把狀態(tài)追蹤清楚。接口方法用途關(guān)鍵字段/api/printPOST提交打印任務(wù)html、printer、copies、paperSize、orientation、margin/api/printersGET獲取本機(jī)已安裝打印機(jī)列表無/api/task/:idGET查詢指定任務(wù)狀態(tài)taskId/api/task/:id/cancelPOST取消排隊(duì)中的任務(wù)taskId提交任務(wù)時(shí)請(qǐng)求體統(tǒng)一用 JSON。下面是一個(gè)最小請(qǐng)求的例子{ html: h1測(cè)試單據(jù)/h1, printer: , copies: 1, paperSize: A4, orientation: portrait }響應(yīng)統(tǒng)一返回三要素code、taskId、message。code為 0 表示任務(wù)已被接收不等于打印成功taskId是后續(xù)查詢狀態(tài)的憑證message留給中間件返回人類可讀的提示。這個(gè)約定避免了「前端以為成功、打印機(jī)沒出紙」的邊界模糊。printer字段設(shè)計(jì)成可選項(xiàng)是有原因的?，F(xiàn)場(chǎng)打印機(jī)名經(jīng)常被實(shí)施人員改來改去網(wǎng)頁端寫死后一旦驅(qū)動(dòng)重裝就全部失效。缺省情況下中間件交給系統(tǒng)默認(rèn)打印機(jī)處理把打印機(jī)名變成可覆蓋參數(shù)能省掉一半的現(xiàn)場(chǎng)故障。3. 從零搭一個(gè) SilentPrint 中間件Node.js 版最小可運(yùn)行實(shí)現(xiàn)3.1 工程骨架與兩個(gè)前置條件動(dòng)手前先確認(rèn)環(huán)境。SilentPrint 中間件我用 Node.js 來搭因?yàn)榭缙脚_(tái)、依賴少而且處理 JSON 請(qǐng)求天然順手。需要本機(jī)已經(jīng)裝了 Node.js 18 或更高版本同時(shí)準(zhǔn)備好一個(gè)可執(zhí)行的無頭瀏覽器路徑用于把 HTML 渲染成 PDF。這個(gè)瀏覽器路徑通過環(huán)境變量SILENT_PRINT_BROWSER指定。目錄結(jié)構(gòu)非常簡(jiǎn)單單文件就能起服務(wù)。創(chuàng)建一個(gè)silentprint-server目錄里面放一個(gè)app.js就夠跑通最小鏈路。整個(gè)中間件不依賴任何第三方 HTTP 框架Node 內(nèi)置的http模塊完全夠用減少依賴意味著減少現(xiàn)場(chǎng)部署時(shí)的翻車點(diǎn)。mkdir silentprint-server cd silentprint-server npm init -y初始化完package.json后先設(shè)置環(huán)境變量。Windows 的命令行里可以用set類 Unix 系統(tǒng)用exportexport SILENT_PRINT_BROWSER/usr/bin/chromium-browser如果不設(shè)置這個(gè)變量后面渲染 HTML 的那一步會(huì)直接報(bào)錯(cuò)。這個(gè)配置是「先于代碼」存在的我第一次帶團(tuán)隊(duì)做的時(shí)候漏了這一步服務(wù)起來之后所有任務(wù)都返回渲染失敗查了半天才發(fā)現(xiàn)是路徑?jīng)]配。3.2 核心打印接口HTML 進(jìn)、PDF 出、送給打印機(jī)下面這段代碼是中間件的主入口實(shí)現(xiàn)了接收 HTML、渲染 PDF、送入打印隊(duì)列三個(gè)核心動(dòng)作。貼到一個(gè)app.js文件里.listen()跑起來就是一個(gè)可用的靜默打印服務(wù)。// silentprint-server/app.js const http require(http); const fs require(fs); const os require(os); const path require(path); const { exec, execFile } require(child_process); const crypto require(crypto); const PORT 9388; const HOST 127.0.0.1; const TMP_DIR path.join(os.tmpdir(), silentprint); // 從環(huán)境變量讀無頭瀏覽器路徑避免把具體瀏覽器寫死在代碼里 const BROWSER process.env.SILENT_PRINT_BROWSER; // 簡(jiǎn)單內(nèi)存隊(duì)列生產(chǎn)環(huán)境建議換 Redis 或數(shù)據(jù)庫(kù)持久化 const taskQueue []; const activePrinters new Set(); let draining false; // JSON 響應(yīng)統(tǒng)一格式code 為 0 表示任務(wù)已接收 function sendJSON(res, obj) { res.writeHead(200, { Content-Type: application/json, Access-Control-Allow-Origin: *, Access-Control-Allow-Headers: Content-Type }); res.end(JSON.stringify(obj)); } function readBody(req) { return new Promise((resolve, reject) { let body ; req.on(data, chunk body chunk); req.on(end, () { try { resolve(JSON.parse(body)); } catch (e) { reject(e); } }); req.on(error, reject); }); } // 把網(wǎng)頁傳來的 HTML 字符串寫成臨時(shí)文件再用無頭瀏覽器渲染成 PDF function renderHtmlToPdf(html, pdfPath) { return new Promise((resolve, reject) { if (!html || !html.trim()) return reject(new Error(HTML 內(nèi)容為空)); if (!BROWSER) return reject(new Error(未設(shè)置 SILENT_PRINT_BROWSER 環(huán)境變量)); const htmlPath pdfPath .html; fs.writeFileSync(htmlPath, html, utf8); const cmd ${BROWSER} --headless --disable-gpu --print-to-pdf${pdfPath} --no-pdf-header-footer file://${htmlPath}; exec(cmd, { timeout: 30000 }, err { if (err) return reject(err); resolve(pdfPath); }); }); } const server http.createServer(async (req, res) { // 只處理 POST /api/print其余接口按 404 處理 if (req.method POST req.url /api/print) { let payload; try { payload await readBody(req); } catch (e) { return sendJSON(res, { code: 400, taskId: , message: 請(qǐng)求體不是合法 JSON }); } const { html, printer , copies 1 } payload; if (!html) return sendJSON(res, { code: 400, taskId: , message: html 字段不能為空 }); if (!Number.isInteger(copies) || copies 1 || copies 99) { return sendJSON(res, { code: 400, taskId: , message: copies 必須是 1~99 的整數(shù) }); } // 用隨機(jī)串做任務(wù)號(hào)方便排查 const taskId crypto.randomBytes(8).toString(hex); const pdfPath path.join(TMP_DIR, taskId .pdf); fs.mkdirSync(TMP_DIR, { recursive: true }); try { await renderHtmlToPdf(html, pdfPath); } catch (e) { return sendJSON(res, { code: 500, taskId: , message: 渲染失敗: e.message }); } taskQueue.push({ taskId, pdfPath, printer, copies, status: queued, retries: 0 }); drainQueue(); return sendJSON(res, { code: 0, taskId, message: 任務(wù)已接收 }); } if (req.method OPTIONS) { return res.writeHead(204).end(); } sendJSON(res, { code: 404, taskId: , message: 接口不存在 }); }); server.listen(PORT, HOST, () { console.log(SilentPrint 中間件已啟動(dòng): http://${HOST}:${PORT}); });這段代碼有四個(gè)關(guān)鍵參數(shù)和邏輯要說明。第一個(gè)是HOST設(shè)為127.0.0.1只在本機(jī)開放端口防止局域網(wǎng)內(nèi)其他設(shè)備直接往里塞打印任務(wù)。如果業(yè)務(wù)系統(tǒng)部署在別的機(jī)器需要把HOST改成0.0.0.0同時(shí)必須在接口里加一個(gè) token 校驗(yàn)否則等于對(duì)外開了一個(gè)無限打印的端口。第二個(gè)參數(shù)是timeout: 30000渲染 HTML 到 PDF 一般不超過 10 秒30 秒超時(shí)足夠。如果現(xiàn)場(chǎng)機(jī)器性能差大單據(jù)渲染慢這個(gè)值可以調(diào)大但不要超過 60 秒否則用戶會(huì)以為系統(tǒng)卡死了。第三個(gè)看點(diǎn)是--no-pdf-header-footer無頭瀏覽器默認(rèn)會(huì)在 PDF 頁眉打印標(biāo)題和頁腳打印頁碼單據(jù)上帶著頁眉很難看。這個(gè)參數(shù)必須帶上否則出紙的左上角和右下角各多一行雜信息。第四個(gè)需要注意sendJSON里加的 CORS 頭。網(wǎng)頁端如果跑在另一個(gè)端口或另一個(gè)域名下瀏覽器跨域請(qǐng)求會(huì)被攔加Access-Control-Allow-Origin: *是開發(fā)期最省事的方式。上生產(chǎn)時(shí)最好把這個(gè)*收斂成你的業(yè)務(wù)域名配合 token 一起用。3.3 網(wǎng)頁端只用一行 fetch前端觸發(fā)靜默打印的最小頁面中間件就緒后網(wǎng)頁端反而簡(jiǎn)單。下面這段是一個(gè)可運(yùn)行的 HTML 頁面點(diǎn)按鈕就把一段內(nèi)容靜默打印出來!DOCTYPE html html langzh-CN head meta charsetutf-8 title靜默打印演示/title /head body button idbtn打印測(cè)試單據(jù)/button script const btn document.getElementById(btn); btn.addEventListener(click, async () { const response await fetch(http://127.0.0.1:9388/api/print, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ html: h1測(cè)試單據(jù)/h1p打印時(shí)間 new Date().toLocaleString() /p, printer: , copies: 1 }) }); const data await response.json(); if (data.code 0) { btn.textContent 已入隊(duì) data.taskId; } else { alert(data.message); } }); /script /body /html這段代碼里最值得注意的不是 fetch 本身而是html字段里的內(nèi)容。網(wǎng)頁獲取真實(shí)單據(jù)內(nèi)容時(shí)我習(xí)慣用document.getElementById(receipt).outerHTML取 DOM但這樣拿到的內(nèi)容里樣式是外鏈 CSS 寫的送到無頭瀏覽器時(shí)不會(huì)自動(dòng)加載打出來會(huì)是一堆沒有格式的裸文本。正確做法是把需要用到的樣式內(nèi)聯(lián)到style標(biāo)簽里或者干脆把整個(gè)style塊拼進(jìn) HTML 字符串一起提交。按鈕的交互也建議加一層防抖。用戶連續(xù)點(diǎn)五次前端就發(fā)五個(gè)任務(wù)如果每臺(tái)打印機(jī)還串行處理任務(wù)隊(duì)列越排越長(zhǎng)。實(shí)際項(xiàng)目里我一般會(huì)在點(diǎn)擊后把按鈕置灰 3 秒或用一個(gè)標(biāo)志位拒絕重復(fù)點(diǎn)擊這比在中間件里做任務(wù)去重成本低得多。4. 打印機(jī)綁定與打印參數(shù)調(diào)優(yōu)從「能打」到「每次都一樣」4.1 枚舉本機(jī)打印機(jī)列表別讓打印機(jī)名靠猜SilentPrint 接口里printer參數(shù)可以留空但跑通鏈路之后還是要面對(duì)一個(gè)現(xiàn)實(shí)問題怎么知道系統(tǒng)里的打印機(jī)到底叫什么名字打印隊(duì)列里顯示的名稱、驅(qū)動(dòng)名稱、系統(tǒng)枚舉名稱經(jīng)常不完全一致讓用戶手填就是制造現(xiàn)場(chǎng)故障。我在中間件里加了一個(gè)打印機(jī)枚舉接口類 Unix 系統(tǒng)用lpstatWindows 用系統(tǒng)自帶的wmic命令拿到設(shè)備名列表。下面是補(bǔ)充實(shí)現(xiàn)function listPrinters(callback) { if (process.platform win32) { // Windows 使用 wmic 枚舉打印機(jī)名 execFile(wmic, [printer, get, name], (err, stdout) { if (err) return callback([]); const lines stdout.split(\n) .map(l l.replace(/^NAME/i, ).trim()) .filter(l l.length 0); callback(lines); }); } else { // 類 Unix 使用 lpstat -p 查看已連接打印機(jī) exec(lpstat -p, (err, stdout) { if (err) return callback([]); const lines stdout.split(\n) .filter(l l.trim().startsWith(printer )) .map(l l.trim().replace(/^printer\s/, ).split( )[0]); callback(lines); }); } } app.get(/api/printers, async (req, res) { listPrinters(list { sendJSON(res, { code: 0, taskId: , message: , printers: list }); }); });注意lpstat -p的輸出形如printer HP-LaserJet is idle. enabled since ...這里切字符串取第一段就能拿到打印機(jī)名。Windows 的wmic第一行是表頭Name需要過濾掉。這類的文本解析最容易出問題的是大小寫和多余空格加.trim()是必須的。拿到列表后前端就能在下拉框里動(dòng)態(tài)展示。這樣實(shí)施人員不需要記住打印機(jī)確切名稱選一下就行打印機(jī)驅(qū)動(dòng)重裝后名稱變了頁面刷新即可拿到新列表。4.2 六組必調(diào)的打印參數(shù)紙張、份數(shù)、朝向、邊距、縮放、雙面跑通最小鏈路后打印質(zhì)量全靠參數(shù)控制。我把實(shí)際項(xiàng)目中最常調(diào)的六組參數(shù)列成了一張表參數(shù)類型必填缺省值說明paperSizestring否A4支持 A4、Letter、自定義自定義需配合 CSS 尺寸orientationstring否portraitportrait 縱向、landscape 橫向marginstring否10mm頁邊距傳 CSS 合法值即可fitToPageboolean否false內(nèi)容是否縮放適配紙張寬度duplexstring否offoff 單面、on 雙面長(zhǎng)邊翻轉(zhuǎn)、short 雙面短邊翻轉(zhuǎn)copiesint否1打印份數(shù)限制 1~99份數(shù)和雙面的參數(shù)直接映射到打印命令上。雙面打印在lp命令里對(duì)應(yīng)-o sidestwo-sided-long-edge這個(gè)能力依賴打印機(jī)驅(qū)動(dòng)支持驅(qū)動(dòng)不支持時(shí)命令會(huì)報(bào)錯(cuò)要在前端就把雙面的選項(xiàng)隱藏或禁用。我踩過一次坑一臺(tái)老式熱敏打印機(jī)不支持雙面但網(wǎng)頁端沒做適配用戶選了雙面后整個(gè)隊(duì)列卡住最后靠重啟打印機(jī)才恢復(fù)。紙張和邊距更多是渲染層的事。無頭瀏覽器打印 PDF 時(shí)頁面里的 CSS 優(yōu)先于命令行參數(shù)所以 HTML 里的page規(guī)則應(yīng)該作為最終依據(jù)page { size: A4; margin: 10mm; }這里容易犯的錯(cuò)是把請(qǐng)求里的margin參數(shù)和 HTML 里的 CSS 同時(shí)傳兩邊不一致時(shí)以 CSS 為準(zhǔn)前端改半天請(qǐng)求參數(shù)就是沒效果查到最后才發(fā)現(xiàn)是樣式里寫死了邊距。我的建議是中間件只透?jìng)骷垙埡头较騇argins 一律由網(wǎng)頁端通過 HTML 內(nèi)容控制避免兩套配置打架。4.3 隊(duì)列與重試防止高頻打印把任務(wù)塞爆不處理隊(duì)列的中間件會(huì)遇到一個(gè)典型故障用戶在一個(gè)單據(jù)上點(diǎn)了多次打印多個(gè)打印進(jìn)程同時(shí)調(diào)用打印機(jī)驅(qū)動(dòng)假脫機(jī)服務(wù)直接卡死后面所有任務(wù)排隊(duì)長(zhǎng)達(dá)幾分鐘打印機(jī)面板上永遠(yuǎn)顯示「正在打印」。SilentPrint 必須按打印機(jī)維度串行輸出任務(wù)。下面是隊(duì)列調(diào)度的核心實(shí)現(xiàn)每臺(tái)打印機(jī)同時(shí)只處理一個(gè)任務(wù)失敗自動(dòng)重試兩次async function drainQueue() { if (draining) return; draining true; while (true) { // 找到第一個(gè)排隊(duì)中、且該打印機(jī)未被占用的任務(wù) const task taskQueue.find(t t.status queued !activePrinters.has(t.printer)); if (!task) break; activePrinters.add(task.printer); task.status printing; try { await sendToPrinter(task); task.status done; } catch (err) { task.retries 1; if (task.retries 2) { // 延遲 1 秒后重新排隊(duì)給打印機(jī)恢復(fù)時(shí)間 task.status queued; setTimeout(() drainQueue(), 1000); } else { task.status failed; task.error err.message; } } finally { activePrinters.delete(task.printer); } } draining false; }activePrinters集合是核心它保證同一臺(tái)打印機(jī)不會(huì)同時(shí)被兩個(gè)任務(wù)占用。draining標(biāo)志防止多個(gè)任務(wù)同時(shí)觸發(fā)drainQueue造成并發(fā)重復(fù)調(diào)度。失敗重試的setTimeout1 秒是經(jīng)過實(shí)踐的值太短打印機(jī)沒反應(yīng)過來太長(zhǎng)用戶等得急。這個(gè)隊(duì)列是純內(nèi)存的中間件重啟任務(wù)就丟了。生產(chǎn)環(huán)境我一般會(huì)把任務(wù)狀態(tài)寫進(jìn)本地 SQLite 或 Redis啟動(dòng)時(shí)自動(dòng)把上次未完成的任務(wù)恢復(fù)進(jìn)隊(duì)列。這樣即使中間件半夜崩潰第二天重啟還能繼續(xù)打印不會(huì)丟單。5. 常見踩坑與排查讓靜默打印翻車的五件小事5.1 任務(wù)顯示成功但打印機(jī)紋絲不動(dòng)現(xiàn)象網(wǎng)頁端拿到code: 0任務(wù)狀態(tài)也顯示done但打印機(jī)一整晚沒有出紙。原因這個(gè)坑我排查過一整天才找到源頭。lp命令返回成功只代表任務(wù)已經(jīng)進(jìn)入假脫機(jī)隊(duì)列不代表打印機(jī)真的消費(fèi)了它。常見原因有三個(gè)選錯(cuò)了打印機(jī)名驅(qū)動(dòng)名和共享名不一致、HTML 渲染出的 PDF 是空白的、打印機(jī)處于離線狀態(tài)。解決首先用lpstat -o查看隊(duì)列里有沒有堆積任務(wù)再用一個(gè)最簡(jiǎn)單的純文本文件直接測(cè)試打印機(jī)驅(qū)動(dòng)確認(rèn)驅(qū)動(dòng)本身沒問題。最后回到中間件檢查渲染出來的 PDF 文件大小是否為 0 或只有幾 KB。我的排查順序永遠(yuǎn)是「隊(duì)列 → 驅(qū)動(dòng) → 文件內(nèi)容」按這個(gè)順序能最快定位。5.2 中文字體全部變成小方塊現(xiàn)象HTML 里的中文內(nèi)容打印出來全部是豆腐塊英文數(shù)字正常。原因無頭瀏覽器渲染 PDF 時(shí)依賴系統(tǒng)字體。服務(wù)器或電腦上沒裝中文字體時(shí)它找不到可用字形只能輸出占位符。這和打印機(jī)無關(guān)問題出在渲染環(huán)節(jié)所以打印預(yù)覽和實(shí)際出紙都會(huì)一樣慘。解決在運(yùn)行中間件的系統(tǒng)里安裝一套中文字體常見的是思源黑體或文泉驛安裝后重啟中間件再試。另一個(gè)更徹底的做法是 HTML 里把中文字體聲明為具體字族名但確保系統(tǒng)里真的有那個(gè)字體。如果現(xiàn)場(chǎng)機(jī)器不能動(dòng)系統(tǒng)就把字體文件放到項(xiàng)目目錄里通過FONTCONFIG_PATH環(huán)境變量指過去這也是我在瘦客戶機(jī)上用過的方案。5.3 HTTPS 頁面請(qǐng)求本地 HTTP 中間件被瀏覽器攔截現(xiàn)象網(wǎng)頁部署在 HTTPS 域名下按鈕點(diǎn)擊后控制臺(tái)報(bào)錯(cuò)Mixed Content請(qǐng)求根本發(fā)不出去。原因?yàn)g覽器安全策略默認(rèn)禁止 HTTPS 頁面請(qǐng)求 HTTP 資源。雖然 127.0.0.1 在部分瀏覽器里被豁免但一旦頁面跑在內(nèi)網(wǎng) IP 域名下或者用戶用了其他瀏覽器這個(gè)攔截就會(huì)生效。解決我常用的三種方案。一是把中間件本身也套上 HTTPS 證書自簽證書需要用戶信任一次適合局域網(wǎng)部署二是把打印頁面放在 HTTP 的內(nèi)網(wǎng)環(huán)境和業(yè)務(wù)系統(tǒng)同源三是在瀏覽器啟動(dòng)參數(shù)里把地址標(biāo)記為安全來源但這只能管開發(fā)調(diào)試不能交付給客戶。生產(chǎn)上我傾向第一種給中間件的端口掛一層證書配合一次性的信任引導(dǎo)。5.4 殺毒軟件把中間件當(dāng)木馬隔離現(xiàn)象中間件運(yùn)行一段時(shí)間后進(jìn)程消失網(wǎng)頁端報(bào)連接失敗檢查任務(wù)管理器發(fā)現(xiàn)進(jìn)程沒了。原因SilentPrint 的形態(tài)特征太像木馬了——常駐后臺(tái)、監(jiān)聽本地端口、接收任意網(wǎng)絡(luò)請(qǐng)求、執(zhí)行外部命令。殺毒軟件的主動(dòng)防御會(huì)把這種程序直接隔離沒有商量的余地。解決給中間件做數(shù)字簽名是最正規(guī)的途徑簽名后殺毒軟件會(huì)放行。如果沒有簽名條件至少要保證中間件只監(jiān)聽 127.0.0.1并且把部署目錄加入殺毒軟件白名單。我在交付文檔里專門寫了一節(jié)「安裝后請(qǐng)將安裝目錄加入安全軟件白名單」實(shí)施人員照著做誤殺率大幅下降。不要依賴殺毒軟件的自動(dòng)學(xué)習(xí)主動(dòng)防御不給你學(xué)習(xí)的機(jī)會(huì)。5.5 任務(wù)排隊(duì)了但不按順序打印現(xiàn)象用戶提交了任務(wù) A、B、C打印出來的順序卻是 A、C、B。原因最常見的是前端沒有做防抖多個(gè)請(qǐng)求幾乎同時(shí)到達(dá)中間件任務(wù)雖然進(jìn)了隊(duì)列但drainQueue的查找邏輯只看「排隊(duì)中」而沒看「入隊(duì)時(shí)間」任務(wù) C 可能先被找到。另一種可能是打印機(jī)驅(qū)動(dòng)本身開了并行處理多個(gè)作業(yè)同時(shí)送進(jìn)去由驅(qū)動(dòng)層面打亂了順序。解決隊(duì)列查找改成按taskId或入隊(duì)序號(hào)排序確保先進(jìn)先出。打印機(jī)驅(qū)動(dòng)層面關(guān)掉「啟用后臺(tái)打印」的并行選項(xiàng)讓作業(yè)嚴(yán)格按提交順序打印。這兩處都改了之后亂序問題才根治。尤其是連打幾十張標(biāo)簽紙時(shí)順序錯(cuò)一張整卷標(biāo)簽全部報(bào)廢這是打印應(yīng)用里最嚴(yán)重的質(zhì)量問題。6. 進(jìn)階用 WebSocket 把打印狀態(tài)實(shí)時(shí)推回網(wǎng)頁業(yè)務(wù)方不滿足于「點(diǎn)了按鈕就等」他們想要「按鈕邊上有個(gè)狀態(tài)燈打完了變綠」。HTTP 輪詢能實(shí)現(xiàn)但中間件這種本地服務(wù)用 WebSocket 推送更干凈也讓中間件從一個(gè)「盲發(fā)任務(wù)」的工具變成一個(gè)可觀測(cè)的任務(wù)中心。在中間件里引入一個(gè) WebSocket 服務(wù)端庫(kù)監(jiān)聽 9389 端口和 HTTP 服務(wù)并存。當(dāng)drainQueue里任務(wù)狀態(tài)變化時(shí)主動(dòng)向前端推送一條消息// 引入 WebSocket 服務(wù)端庫(kù)并監(jiān)聽 9389 端口 const { WebSocketServer } require(ws); const wss new WebSocketServer({ port: 9389 }); // 在任務(wù)狀態(tài)變化后調(diào)用通知前端頁面 function notifyTaskStatus(task) { const message JSON.stringify({ type: taskStatus, taskId: task.taskId, status: task.status, error: task.error || }); wss.clients.forEach(client { if (client.readyState 1) { client.send(message); } }); }前端接收推送比輪詢簡(jiǎn)單得多而且實(shí)時(shí)性更好// 網(wǎng)頁端建立 WebSocket 連接監(jiān)聽打印狀態(tài) const printerSocket new WebSocket(ws://127.0.0.1:9389); printerSocket.onmessage event { const msg JSON.parse(event.data); if (msg.type taskStatus msg.taskId currentTaskId) { // 更新按鈕文案已入隊(duì) - 打印中 - 打印完成 statusLabel.textContent { queued: 已排隊(duì), printing: 打印中, done: 已完成, failed: 失敗 }[msg.status] || 未知; } }; // 斷線重連中間件重啟后還能自動(dòng)恢復(fù)狀態(tài)推送 printerSocket.onclose () { setTimeout(() { location.reload(); }, 3000); };一個(gè)值得注意的設(shè)計(jì)細(xì)節(jié)前端必須用taskId來過濾推送消息因?yàn)橥慌_(tái)機(jī)器上可能有多個(gè)標(biāo)簽頁在打印不過濾會(huì)把別人的狀態(tài)也顯示出來。另外 WebSocket 連接是 9389 端口和 HTTP 的 9388 分開好處是打印任務(wù)量大時(shí)不會(huì)互相阻塞。斷線重連那段代碼我用的是最簡(jiǎn)單的location.reload()。中間件重啟期間網(wǎng)頁會(huì)自動(dòng)刷新重新建立連接省去了手工維護(hù)心跳的麻煩。希望這個(gè)技巧能在你的項(xiàng)目里派上用場(chǎng)靜默打印這條路走到這里就是完整閉環(huán)了。本文還有配套的精品資源點(diǎn)擊獲取