簡(jiǎn)介SilentPrint 是一款專(zhuān)為網(wǎng)頁(yè)靜默打印設(shè)計(jì)的 JavaScript 中間件面向需要無(wú)交互自動(dòng)打印場(chǎng)景的 Web 開(kāi)發(fā)者可應(yīng)用于發(fā)票收據(jù)、報(bào)表合同及自助服務(wù)終端等場(chǎng)景。壓縮包共 44 個(gè)文件以 22 個(gè) JS 腳本和 3 個(gè) Vue 組件為核心另含 HTML 頁(yè)面、Markdown 文檔、YAML 配置、ESLint 規(guī)則及圖標(biāo)等整體僅 154KB輕量且模塊劃分清晰。通過(guò)示例工程可系統(tǒng)學(xué)習(xí)靜默打印的完整實(shí)現(xiàn)鏈路利用 CSS 媒體查詢調(diào)整打印樣式結(jié)合 HTML2Canvas 將頁(yè)面渲染為圖片后發(fā)送至打印機(jī)并借助 Web Worker 在后臺(tái)執(zhí)行打印任務(wù)以避免阻塞主線程。項(xiàng)目基于 Electron-Vue 搭建包含主進(jìn)程與渲染進(jìn)程通信、webpack 多環(huán)境配置和演示頁(yè)面能幫助開(kāi)發(fā)者理解打印流程控制、瀏覽器兼容性處理及降級(jí)方案。目前已有 5277 人學(xué)習(xí)下載適合具有一定前端基礎(chǔ)、希望為 Web 應(yīng)用快速接入后臺(tái)打印能力的開(kāi)發(fā)者參考。1. SilentPrint 是干什么的把「選打印機(jī)、調(diào)參數(shù)、點(diǎn)確定」這三步從網(wǎng)頁(yè)里去掉窗口辦事、倉(cāng)庫(kù)開(kāi)單、藥房貼簽這類(lèi)場(chǎng)景里每天都會(huì)重復(fù)一個(gè)動(dòng)作打開(kāi)網(wǎng)頁(yè)上的單據(jù)點(diǎn)打印瀏覽器彈出一個(gè)打印預(yù)覽框再選一次打印機(jī)、核對(duì)紙張方向、調(diào)頁(yè)邊距最后點(diǎn)確定。一套動(dòng)作五六次點(diǎn)擊一天重復(fù)上百次手快的人也會(huì)煩。SilentPrint 要解決的就是這件事——它是一個(gè)常駐本機(jī)的中間件網(wǎng)頁(yè)通過(guò) HTTP 接口把打印任務(wù)丟給它它直接把內(nèi)容送進(jìn)打印機(jī)隊(duì)列全程不彈預(yù)覽、不出對(duì)話框、不需要人工介入。對(duì)網(wǎng)頁(yè)前端來(lái)說(shuō)靜默打印從一個(gè)「瀏覽器不允許的事」變成了「一次普通請(qǐng)求」。這篇文章會(huì)從鏈路設(shè)計(jì)、最小實(shí)現(xiàn)、參數(shù)調(diào)優(yōu)到高頻踩坑點(diǎn)講透適合那些已經(jīng)有網(wǎng)頁(yè)管理系統(tǒng)、不想改造業(yè)務(wù)流程只想讓單據(jù)能直接出紙的開(kāi)發(fā)者和實(shí)施人員。2. 靜默打印鏈路拆解瀏覽器為什么不肯靜默中間件怎么接住2.1 瀏覽器打印的沙箱邊界不是做不到是不允許先回答一個(gè)很多人問(wèn)過(guò)的問(wèn)題為什么網(wǎng)頁(yè)不能直接調(diào)用系統(tǒng)打印隨便打開(kāi)一個(gè)網(wǎng)頁(yè)的控制臺(tái)輸入print()就知道瀏覽器只提供了window.print()這個(gè)入口而它的行為是「彈出打印對(duì)話框」沒(méi)有任何參數(shù)能讓它跳過(guò)對(duì)話框直接出紙。這不是瀏覽器偷懶而是安全模型故意這樣設(shè)計(jì)的。網(wǎng)頁(yè)運(yùn)行在沙箱里不能直接訪問(wèn)文件系統(tǒng)、不能調(diào)系統(tǒng) API、也不能感知本機(jī)裝了什么打印機(jī)。如果允許一個(gè)陌生網(wǎng)頁(yè)直接往打印機(jī)塞任務(wù)那廣告頁(yè)面完全可以循環(huán)打印上千張紙把公司耗材打光甚至配合驅(qū)動(dòng)漏洞做更危險(xiǎn)的事。所以「靜默打印」這個(gè)需求本質(zhì)上是在和瀏覽器的安全邊界對(duì)著干硬用純前端方案繞不過(guò)去。我在早期做過(guò)一次嘗試用隱藏的 iframe 加載內(nèi)容再調(diào)print()結(jié)果打印對(duì)話框照樣彈出來(lái)而且 iframe 里的樣式還經(jīng)常丟。后來(lái)又試過(guò) ActiveX 控件、瀏覽器插件要么只能在特定內(nèi)核里跑要么每次升級(jí)瀏覽器就失效。最后穩(wěn)定下來(lái)的方案就是現(xiàn)在大家普遍采用的做法在瀏覽器之外放一個(gè)本地中間件它不依賴網(wǎng)頁(yè)權(quán)限由操作系統(tǒng)直接授權(quán)去調(diào)用打印能力。這套鏈路拆開(kāi)看是三層。第一層是網(wǎng)頁(yè)端負(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)頁(yè)只在第一層中間件隔斷了瀏覽器安全策略和操作系統(tǒng)打印接口之間的沖突。2.2 中間件在鏈路里的角色只做四件事別讓它背更多包袱SilentPrint 中間件的職責(zé)邊界是我在實(shí)際項(xiàng)目里反復(fù)調(diào)整后定下來(lái)的。它只做四件事提供 HTTP 服務(wù)、校驗(yàn)打印參數(shù)、調(diào)用系統(tǒng)打印接口、把任務(wù)狀態(tài)回傳。任何超出這四件事的功能都不應(yīng)該塞進(jìn)中間件里。這個(gè)邊界很重要。常見(jiàn)的反面教材是把模板渲染也塞進(jìn)中間件——讓中間件去數(shù)據(jù)庫(kù)取數(shù)據(jù)、套模板、生成單據(jù)?？雌饋?lái)省了一次 HTTP 請(qǐng)求但中間件開(kāi)始依賴業(yè)務(wù)系統(tǒng)升級(jí)業(yè)務(wù)時(shí)還得同步升級(jí)打印端現(xiàn)場(chǎng)實(shí)施的人會(huì)瘋掉。我一般會(huì)把「生成內(nèi)容」和「打印內(nèi)容」嚴(yán)格分開(kāi)網(wǎng)頁(yè)負(fù)責(zé)把 HTML 或 PDF 內(nèi)容算好中間件只負(fù)責(zé)把它打出來(lái)。另一個(gè)容易越界的點(diǎn)是權(quán)限管理。有人希望中間件自己管用戶權(quán)限誰(shuí)有權(quán)限打印、誰(shuí)沒(méi)有。這個(gè)我也不建議做。權(quán)限應(yīng)該在業(yè)務(wù)系統(tǒng)里控制中間件只認(rèn)識(shí)業(yè)務(wù)系統(tǒng)下發(fā)的任務(wù)不認(rèn)識(shí)具體操作人。它就像一個(gè)打印機(jī)代理任何可以訪問(wèn)它的服務(wù)都能提交任務(wù)安全邊界靠「誰(shuí)能訪問(wèn)這個(gè)端口」來(lái)控制而不是在中間件里再寫(xiě)一套用戶體系。系統(tǒng)的差異也應(yīng)該收在中間件內(nèi)部。Windows、Linux、macOS 的打印命令完全不同但網(wǎng)頁(yè)端不需要知道這些。前端只需要POST一個(gè) JSON中間件根據(jù)運(yùn)行平臺(tái)決定調(diào)lp還是系統(tǒng)打印接口。這個(gè)「差異隔離」是中間件存在的最重要價(jià)值比省幾次點(diǎn)擊更關(guān)鍵。2.3 先定協(xié)議SilentPrint 的四個(gè)核心接口寫(xiě)代碼前我習(xí)慣先把接口協(xié)議定下來(lái)。SilentPrint 的協(xié)議設(shè)計(jì)遵循「請(qǐng)求要簡(jiǎn)單、響應(yīng)要明確」的原則網(wǎng)頁(yè)端只關(guān)心任務(wù)有沒(méi)有被接收中間件負(fù)責(zé)把狀態(tài)追蹤清楚。接口方法用途關(guān)鍵字段/api/printPOST提交打印任務(wù)html、printer、copies、paperSize、orientation、margin/api/printersGET獲取本機(jī)已安裝打印機(jī)列表無(wú)/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留給中間件返回人類(lèi)可讀的提示。這個(gè)約定避免了「前端以為成功、打印機(jī)沒(méi)出紙」的邊界模糊。printer字段設(shè)計(jì)成可選項(xiàng)是有原因的?，F(xiàn)場(chǎng)打印機(jī)名經(jīng)常被實(shí)施人員改來(lái)改去網(wǎng)頁(yè)端寫(xiě)死后一旦驅(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 來(lái)搭因?yàn)榭缙脚_(tái)、依賴少而且處理 JSON 請(qǐng)求天然順手。需要本機(jī)已經(jīng)裝了 Node.js 18 或更高版本同時(shí)準(zhǔn)備好一個(gè)可執(zhí)行的無(wú)頭瀏覽器路徑用于把 HTML 渲染成 PDF。這個(gè)瀏覽器路徑通過(guò)環(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í)的翻車(chē)點(diǎn)。mkdir silentprint-server cd silentprint-server npm init -y初始化完package.json后先設(shè)置環(huán)境變量。Windows 的命令行里可以用set類(lèi) Unix 系統(tǒng)用exportexport SILENT_PRINT_BROWSER/usr/bin/chromium-browser如果不設(shè)置這個(gè)變量后面渲染 HTML 的那一步會(huì)直接報(bào)錯(cuò)。這個(gè)配置是「先于代碼」存在的我第一次帶團(tuán)隊(duì)做的時(shí)候漏了這一步服務(wù)起來(lái)之后所有任務(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()跑起來(lái)就是一個(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)境變量讀無(wú)頭瀏覽器路徑避免把具體瀏覽器寫(xiě)死在代碼里 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)頁(yè)傳來(lái)的 HTML 字符串寫(xiě)成臨時(shí)文件再用無(wú)頭瀏覽器渲染成 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ù)和邏輯要說(shuō)明。第一個(gè)是HOST設(shè)為127.0.0.1只在本機(jī)開(kāi)放端口防止局域網(wǎng)內(nèi)其他設(shè)備直接往里塞打印任務(wù)。如果業(yè)務(wù)系統(tǒng)部署在別的機(jī)器需要把HOST改成0.0.0.0同時(shí)必須在接口里加一個(gè) token 校驗(yàn)否則等于對(duì)外開(kāi)了一個(gè)無(wú)限打印的端口。第二個(gè)參數(shù)是timeout: 30000渲染 HTML 到 PDF 一般不超過(guò) 10 秒30 秒超時(shí)足夠。如果現(xiàn)場(chǎng)機(jī)器性能差大單據(jù)渲染慢這個(gè)值可以調(diào)大但不要超過(guò) 60 秒否則用戶會(huì)以為系統(tǒng)卡死了。第三個(gè)看點(diǎn)是--no-pdf-header-footer無(wú)頭瀏覽器默認(rèn)會(huì)在 PDF 頁(yè)眉打印標(biāo)題和頁(yè)腳打印頁(yè)碼單據(jù)上帶著頁(yè)眉很難看。這個(gè)參數(shù)必須帶上否則出紙的左上角和右下角各多一行雜信息。第四個(gè)需要注意sendJSON里加的 CORS 頭。網(wǎng)頁(yè)端如果跑在另一個(gè)端口或另一個(gè)域名下瀏覽器跨域請(qǐng)求會(huì)被攔加Access-Control-Allow-Origin: *是開(kāi)發(fā)期最省事的方式。上生產(chǎn)時(shí)最好把這個(gè)*收斂成你的業(yè)務(wù)域名配合 token 一起用。3.3 網(wǎng)頁(yè)端只用一行 fetch前端觸發(fā)靜默打印的最小頁(yè)面中間件就緒后網(wǎng)頁(yè)端反而簡(jiǎn)單。下面這段是一個(gè)可運(yùn)行的 HTML 頁(yè)面點(diǎn)按鈕就把一段內(nèi)容靜默打印出來(lá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)頁(yè)獲取真實(shí)單據(jù)內(nèi)容時(shí)我習(xí)慣用document.getElementById(receipt).outerHTML取 DOM但這樣拿到的內(nèi)容里樣式是外鏈 CSS 寫(xiě)的送到無(wú)頭瀏覽器時(shí)不會(huì)自動(dòng)加載打出來(lái)會(huì)是一堆沒(méi)有格式的裸文本。正確做法是把需要用到的樣式內(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í)問(wèn)題怎么知道系統(tǒng)里的打印機(jī)到底叫什么名字打印隊(duì)列里顯示的名稱、驅(qū)動(dòng)名稱、系統(tǒng)枚舉名稱經(jīng)常不完全一致讓用戶手填就是制造現(xiàn)場(chǎng)故障。我在中間件里加了一個(gè)打印機(jī)枚舉接口類(lèi) 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 { // 類(lèi) 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需要過(guò)濾掉。這類(lèi)的文本解析最容易出問(wèn)題的是大小寫(xiě)和多余空格加.trim()是必須的。拿到列表后前端就能在下拉框里動(dòng)態(tài)展示。這樣實(shí)施人員不需要記住打印機(jī)確切名稱選一下就行打印機(jī)驅(qū)動(dòng)重裝后名稱變了頁(yè)面刷新即可拿到新列表。4.2 六組必調(diào)的打印參數(shù)紙張、份數(shù)、朝向、邊距、縮放、雙面跑通最小鏈路后打印質(zhì)量全靠參數(shù)控制。我把實(shí)際項(xiàng)目中最常調(diào)的六組參數(shù)列成了一張表參數(shù)類(lèi)型必填缺省值說(shuō)明paperSizestring否A4支持 A4、Letter、自定義自定義需配合 CSS 尺寸orientationstring否portraitportrait 縱向、landscape 橫向marginstring否10mm頁(yè)邊距傳 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)隱藏或禁用。我踩過(guò)一次坑一臺(tái)老式熱敏打印機(jī)不支持雙面但網(wǎng)頁(yè)端沒(méi)做適配用戶選了雙面后整個(gè)隊(duì)列卡住最后靠重啟打印機(jī)才恢復(fù)。紙張和邊距更多是渲染層的事。無(wú)頭瀏覽器打印 PDF 時(shí)頁(yè)面里的 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ù)就是沒(méi)效果查到最后才發(fā)現(xiàn)是樣式里寫(xiě)死了邊距。我的建議是中間件只透?jìng)骷垙埡头较騇argins 一律由網(wǎng)頁(yè)端通過(guò) 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)過(guò)實(shí)踐的值太短打印機(jī)沒(méi)反應(yīng)過(guò)來(lái)太長(zhǎng)用戶等得急。這個(gè)隊(duì)列是純內(nèi)存的中間件重啟任務(wù)就丟了。生產(chǎn)環(huán)境我一般會(huì)把任務(wù)狀態(tài)寫(xiě)進(jìn)本地 SQLite 或 Redis啟動(dòng)時(shí)自動(dòng)把上次未完成的任務(wù)恢復(fù)進(jìn)隊(duì)列。這樣即使中間件半夜崩潰第二天重啟還能繼續(xù)打印不會(huì)丟單。5. 常見(jiàn)踩坑與排查讓靜默打印翻車(chē)的五件小事5.1 任務(wù)顯示成功但打印機(jī)紋絲不動(dòng)現(xiàn)象網(wǎng)頁(yè)端拿到code: 0任務(wù)狀態(tài)也顯示done但打印機(jī)一整晚沒(méi)有出紙。原因這個(gè)坑我排查過(guò)一整天才找到源頭。lp命令返回成功只代表任務(wù)已經(jīng)進(jìn)入假脫機(jī)隊(duì)列不代表打印機(jī)真的消費(fèi)了它。常見(jiàn)原因有三個(gè)選錯(cuò)了打印機(jī)名驅(qū)動(dòng)名和共享名不一致、HTML 渲染出的 PDF 是空白的、打印機(jī)處于離線狀態(tài)。解決首先用lpstat -o查看隊(duì)列里有沒(méi)有堆積任務(wù)再用一個(gè)最簡(jiǎn)單的純文本文件直接測(cè)試打印機(jī)驅(qū)動(dòng)確認(rèn)驅(qū)動(dòng)本身沒(méi)問(wèn)題。最后回到中間件檢查渲染出來(lái)的 PDF 文件大小是否為 0 或只有幾 KB。我的排查順序永遠(yuǎn)是「隊(duì)列 → 驅(qū)動(dòng) → 文件內(nèi)容」按這個(gè)順序能最快定位。5.2 中文字體全部變成小方塊現(xiàn)象HTML 里的中文內(nèi)容打印出來(lái)全部是豆腐塊英文數(shù)字正常。原因無(wú)頭瀏覽器渲染 PDF 時(shí)依賴系統(tǒng)字體。服務(wù)器或電腦上沒(méi)裝中文字體時(shí)它找不到可用字形只能輸出占位符。這和打印機(jī)無(wú)關(guān)問(wèn)題出在渲染環(huán)節(jié)所以打印預(yù)覽和實(shí)際出紙都會(huì)一樣慘。解決在運(yùn)行中間件的系統(tǒng)里安裝一套中文字體常見(jiàn)的是思源黑體或文泉驛安裝后重啟中間件再試。另一個(gè)更徹底的做法是 HTML 里把中文字體聲明為具體字族名但確保系統(tǒng)里真的有那個(gè)字體。如果現(xiàn)場(chǎng)機(jī)器不能動(dòng)系統(tǒng)就把字體文件放到項(xiàng)目目錄里通過(guò)FONTCONFIG_PATH環(huán)境變量指過(guò)去這也是我在瘦客戶機(jī)上用過(guò)的方案。5.3 HTTPS 頁(yè)面請(qǐng)求本地 HTTP 中間件被瀏覽器攔截現(xiàn)象網(wǎng)頁(yè)部署在 HTTPS 域名下按鈕點(diǎn)擊后控制臺(tái)報(bào)錯(cuò)Mixed Content請(qǐng)求根本發(fā)不出去。原因?yàn)g覽器安全策略默認(rèn)禁止 HTTPS 頁(yè)面請(qǐng)求 HTTP 資源。雖然 127.0.0.1 在部分瀏覽器里被豁免但一旦頁(yè)面跑在內(nèi)網(wǎng) IP 域名下或者用戶用了其他瀏覽器這個(gè)攔截就會(huì)生效。解決我常用的三種方案。一是把中間件本身也套上 HTTPS 證書(shū)自簽證書(shū)需要用戶信任一次適合局域網(wǎng)部署二是把打印頁(yè)面放在 HTTP 的內(nèi)網(wǎng)環(huán)境和業(yè)務(wù)系統(tǒng)同源三是在瀏覽器啟動(dòng)參數(shù)里把地址標(biāo)記為安全來(lái)源但這只能管開(kāi)發(fā)調(diào)試不能交付給客戶。生產(chǎn)上我傾向第一種給中間件的端口掛一層證書(shū)配合一次性的信任引導(dǎo)。5.4 殺毒軟件把中間件當(dāng)木馬隔離現(xiàn)象中間件運(yùn)行一段時(shí)間后進(jìn)程消失網(wǎng)頁(yè)端報(bào)連接失敗檢查任務(wù)管理器發(fā)現(xiàn)進(jìn)程沒(méi)了。原因SilentPrint 的形態(tài)特征太像木馬了——常駐后臺(tái)、監(jiān)聽(tīng)本地端口、接收任意網(wǎng)絡(luò)請(qǐng)求、執(zhí)行外部命令。殺毒軟件的主動(dòng)防御會(huì)把這種程序直接隔離沒(méi)有商量的余地。解決給中間件做數(shù)字簽名是最正規(guī)的途徑簽名后殺毒軟件會(huì)放行。如果沒(méi)有簽名條件至少要保證中間件只監(jiān)聽(tīng) 127.0.0.1并且把部署目錄加入殺毒軟件白名單。我在交付文檔里專(zhuān)門(mén)寫(xiě)了一節(jié)「安裝后請(qǐng)將安裝目錄加入安全軟件白名單」實(shí)施人員照著做誤殺率大幅下降。不要依賴殺毒軟件的自動(dòng)學(xué)習(xí)主動(dòng)防御不給你學(xué)習(xí)的機(jī)會(huì)。5.5 任務(wù)排隊(duì)了但不按順序打印現(xiàn)象用戶提交了任務(wù) A、B、C打印出來(lái)的順序卻是 A、C、B。原因最常見(jiàn)的是前端沒(méi)有做防抖多個(gè)請(qǐng)求幾乎同時(shí)到達(dá)中間件任務(wù)雖然進(jìn)了隊(duì)列但drainQueue的查找邏輯只看「排隊(duì)中」而沒(méi)看「入隊(duì)時(shí)間」任務(wù) C 可能先被找到。另一種可能是打印機(jī)驅(qū)動(dòng)本身開(kāi)了并行處理多個(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)格按提交順序打印。這兩處都改了之后亂序問(wèn)題才根治。尤其是連打幾十張標(biāo)簽紙時(shí)順序錯(cuò)一張整卷標(biāo)簽全部報(bào)廢這是打印應(yīng)用里最嚴(yán)重的質(zhì)量問(wèn)題。6. 進(jìn)階用 WebSocket 把打印狀態(tài)實(shí)時(shí)推回網(wǎng)頁(yè)業(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)聽(tīng) 9389 端口和 HTTP 服務(wù)并存。當(dāng)drainQueue里任務(wù)狀態(tài)變化時(shí)主動(dòng)向前端推送一條消息// 引入 WebSocket 服務(wù)端庫(kù)并監(jiān)聽(tīng) 9389 端口 const { WebSocketServer } require(ws); const wss new WebSocketServer({ port: 9389 }); // 在任務(wù)狀態(tài)變化后調(diào)用通知前端頁(yè)面 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)頁(yè)端建立 WebSocket 連接監(jiān)聽(tīng)打印狀態(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來(lái)過(guò)濾推送消息因?yàn)橥慌_(tái)機(jī)器上可能有多個(gè)標(biāo)簽頁(yè)在打印不過(guò)濾會(huì)把別人的狀態(tài)也顯示出來(lái)。另外 WebSocket 連接是 9389 端口和 HTTP 的 9388 分開(kāi)好處是打印任務(wù)量大時(shí)不會(huì)互相阻塞。斷線重連那段代碼我用的是最簡(jiǎn)單的location.reload()。中間件重啟期間網(wǎng)頁(yè)會(huì)自動(dòng)刷新重新建立連接省去了手工維護(hù)心跳的麻煩。希望這個(gè)技巧能在你的項(xiàng)目里派上用場(chǎng)靜默打印這條路走到這里就是完整閉環(huán)了。本文還有配套的精品資源點(diǎn)擊獲取