簡介這份資源面向需要在Web前端實(shí)現(xiàn)PDF導(dǎo)出的開發(fā)者尤其是使用pdfmake時(shí)被中文亂碼問題困擾、希望快速拿到可用方案的人群。資源包圍繞pdfmake導(dǎo)出中文無亂碼PDF這一核心場景提供了一套可直接運(yùn)行的演示環(huán)境省去自行配置中文字體與虛擬文件系統(tǒng)的摸索成本。壓縮包共4個(gè)文件以js腳本和html頁面為主另有系統(tǒng)緩存文件整體約2.36MB體積輕量便于本地保存與二次修改。目前已有1313人學(xué)習(xí)下載說明該方案在實(shí)際開發(fā)中具備一定參考價(jià)值。解壓后打開演示頁面即可在瀏覽器中觸發(fā)下載直觀看到中文正常顯示的導(dǎo)出效果讀者可據(jù)此對(duì)照自身項(xiàng)目理解字體注冊(cè)與文檔定義的關(guān)鍵寫法并在此基礎(chǔ)上替換業(yè)務(wù)數(shù)據(jù)、調(diào)整表格與排版樣式快速遷移到實(shí)際導(dǎo)出功能中。1. 前端導(dǎo)出中文 PDF 的坑pdfmake 這套方案能繞過去做過管理后臺(tái)的都知道導(dǎo)出 PDF 這個(gè)需求看著簡單真上手就翻車。用瀏覽器打印吧分頁和頁眉頁腳根本控不住用后端生成吧前后端來回傳文件、調(diào)接口一個(gè)字段對(duì)不上就得聯(lián)調(diào)半天。更別提中文了——字體沒嵌進(jìn)去導(dǎo)出來滿屏方塊用戶截圖發(fā)過來問“這是什么亂碼”你還得解釋半天。pdfmake 這個(gè)庫就是沖著這類場景來的純前端、聲明式文檔定義、支持自定義字體嵌入導(dǎo)出的中文 PDF 不亂碼分頁、表格、頁眉頁腳都能在代碼里寫死。它適合誰適合那些不想為了一份 PDF 去搭一套后端渲染服務(wù)、又需要穩(wěn)定輸出中文文檔的前端開發(fā)者。下面我按“它怎么組織文檔 → 怎么把中文字體塞進(jìn)去 → 怎么跑起來 → 怎么改”的順序把這份資源拆開講。2. 文檔定義模型拆解pdfmake 是怎么把 JSON 變成 PDF 的pdfmake 的核心思路很直接你不寫繪圖指令你寫一棵“文檔定義樹”庫負(fù)責(zé)把它翻譯成 PDF 的底層對(duì)象。理解這棵樹的結(jié)構(gòu)后面調(diào)樣式、調(diào)分頁才不會(huì)瞎試。2.1 docDefinition 的四個(gè)關(guān)鍵字段一份 pdfmake 文檔就是一個(gè)普通對(duì)象最常用的字段是content、styles、defaultStyle、pageMargins。content是內(nèi)容數(shù)組里面每個(gè)元素可以是一段文字、一個(gè)表格、一張圖片也可以嵌套列columns和棧stack。styles定義命名樣式defaultStyle兜底全局字體和字號(hào)。下面是一個(gè)最小可運(yùn)行的定義// 最小文檔定義一段中文 一個(gè)兩列表格 const docDefinition { // 全局默認(rèn)樣式font 必須指向已注冊(cè)的字體名 defaultStyle: { font: NotoSansSC, // 后面 registerFonts 時(shí)用的名字 fontSize: 11, lineHeight: 1.4 }, // 頁面邊距單位是 pt1pt ≈ 1/72 英寸 pageMargins: [40, 60, 40, 60], content: [ { text: 項(xiàng)目驗(yàn)收?qǐng)?bào)告, style: title }, { text: 本報(bào)告由前端直接生成無需后端參與。, margin: [0, 8, 0, 16] }, { table: { // headerRows: 1 表示第一行是表頭跨頁時(shí)自動(dòng)重復(fù) headerRows: 1, widths: [30%, *], body: [ [字段, 值], [項(xiàng)目名稱, 某跨平臺(tái)系統(tǒng)], [導(dǎo)出時(shí)間, new Date().toLocaleString(zh-CN)] ] } } ], styles: { title: { fontSize: 18, bold: true, margin: [0, 0, 0, 12] } } };這段定義里content的順序就是 PDF 里從上到下的順序margin數(shù)組是[左, 上, 右, 下]這個(gè)順序容易記反我第一次寫的時(shí)候把上下寫顛倒了調(diào)了半天間距。table.widths里*表示剩余寬度自動(dòng)分配30%是相對(duì)頁面可用寬度的百分比。headerRows是個(gè)很實(shí)用的參數(shù)表格跨頁時(shí)表頭會(huì)自動(dòng)重復(fù)不用自己手動(dòng)拆表。2.2 內(nèi)容節(jié)點(diǎn)的嵌套規(guī)則pdfmake 的內(nèi)容節(jié)點(diǎn)可以嵌套但嵌套有邊界columns里放的是并排的列每列本身又是一個(gè)內(nèi)容數(shù)組stack是垂直堆疊等價(jià)于不加任何布局的默認(rèn)行為。真正需要注意的是text字段既可以是一個(gè)字符串也可以是一個(gè)數(shù)組——數(shù)組形式用來做行內(nèi)混排比如一段話里某幾個(gè)字加粗、變色{ text: [ 狀態(tài), { text: 已通過, bold: true, color: #1a7f37 }, 審批人某導(dǎo)師 ] }這種行內(nèi)數(shù)組的寫法在生成帶狀態(tài)標(biāo)記的報(bào)告時(shí)特別順手不用為了一個(gè)加粗詞去拆成多個(gè)段落。但要注意行內(nèi)數(shù)組里的每個(gè)元素只支持文本級(jí)樣式bold、italic、color、fontSize不支持margin這類塊級(jí)屬性寫了也不生效這是很多人調(diào)樣式調(diào)不出來的原因。2.3 分頁與頁眉頁腳的控制點(diǎn)分頁在 pdfmake 里有兩個(gè)層面自動(dòng)分頁和手動(dòng)分頁。自動(dòng)分頁由內(nèi)容高度決定庫會(huì)盡量不讓一個(gè)塊被切斷但表格行、圖片這類原子塊如果放不下就整體挪到下一頁。手動(dòng)分頁用{ text: , pageBreak: after }注意這個(gè)節(jié)點(diǎn)本身要占一個(gè)位置通常放在兩個(gè)章節(jié)之間。頁眉頁腳通過header和footer函數(shù)定義函數(shù)接收當(dāng)前頁碼和總頁數(shù)// 頁腳第 X 頁 / 共 Y 頁 footer: function (currentPage, pageCount) { return { margin: [40, 0, 40, 0], columns: [ { text: 內(nèi)部資料, fontSize: 9, color: #888 }, { text: 第 ${currentPage} 頁 / 共 ${pageCount} 頁, alignment: right, fontSize: 9 } ] }; }這里有個(gè)細(xì)節(jié)footer返回的也是一個(gè)內(nèi)容節(jié)點(diǎn)所以它同樣受defaultStyle的字體影響。如果頁腳中文變成方塊說明字體注冊(cè)那一步?jīng)]覆蓋到不是頁腳本身的問題。pageCount是庫在排版完成后回填的所以頁腳里拿到的總頁數(shù)是準(zhǔn)確的不用擔(dān)心“共 1 頁”這種錯(cuò)誤。3. 中文字體嵌入不亂碼的關(guān)鍵就在這一步中文亂碼的根因只有一個(gè)PDF 里引用的字體沒有嵌入字形閱讀器找不到對(duì)應(yīng)字符就畫方塊。pdfmake 默認(rèn)只帶 Roboto 這類拉丁字體中文必須自己注冊(cè)。這一步做對(duì)了后面基本不會(huì)再有亂碼問題。3.1 字體文件從哪來、放哪常見做法是選一個(gè)開源中文字體比如思源黑體Noto Sans SC或者更輕量的子集字體。完整中文字體動(dòng)輒十幾 MB直接打進(jìn)前端包會(huì)讓首屏體積爆炸所以實(shí)際項(xiàng)目里一般做兩件事一是把字體文件放到靜態(tài)資源目錄按需加載二是用字體子集化工具裁掉用不到的字形。下面假設(shè)字體文件已經(jīng)放在public/fonts/下文件名是NotoSansSC-Regular.ttf。# 目錄結(jié)構(gòu)示意 public/ fonts/ NotoSansSC-Regular.ttf # 常規(guī)體用于正文 NotoSansSC-Bold.ttf # 粗體用于標(biāo)題字體文件必須是 TTF 或 OTFpdfmake 不接受 WOFF/WOFF2這一點(diǎn)在選字體時(shí)就要確認(rèn)別下載完發(fā)現(xiàn)格式不對(duì)又回頭找。3.2 registerFonts 的兩種寫法pdfmake 注冊(cè)字體有兩種方式一種是把字體文件轉(zhuǎn)成 base64 字符串直接內(nèi)聯(lián)適合字體很小或者要打包成單文件的場景另一種是傳 URL讓庫在運(yùn)行時(shí)去加載。URL 方式更清爽但要注意跨域和加載時(shí)序。下面是 URL 方式的寫法import pdfMake from pdfmake/build/pdfmake; import pdfFonts from pdfmake/build/vfs_fonts; // 先掛上默認(rèn)字體表否則 pdfMake 內(nèi)部找不到基礎(chǔ)字體 pdfMake.vfs pdfFonts.pdfMake.vfs; // 注冊(cè)中文字體名字自己定后面 docDefinition 里引用同一個(gè)名字 pdfMake.fonts { NotoSansSC: { normal: /fonts/NotoSansSC-Regular.ttf, bold: /fonts/NotoSansSC-Bold.ttf, italics: /fonts/NotoSansSC-Regular.ttf, // 沒有斜體就用常規(guī)體頂替 bolditalics: /fonts/NotoSansSC-Bold.ttf } };四個(gè)鍵normal、bold、italics、bolditalics必須都給缺一個(gè)的話用到對(duì)應(yīng)樣式時(shí)庫會(huì)報(bào)字體未定義。沒有真正的斜體文件時(shí)用常規(guī)體頂替是常見做法視覺上不會(huì)斜但至少不報(bào)錯(cuò)。pdfMake.vfs那行不能省它是 pdfmake 內(nèi)置的虛擬文件系統(tǒng)默認(rèn)字體表掛上去之后庫才能正常初始化。3.3 生成與下載的完整調(diào)用鏈注冊(cè)完字體生成 PDF 就是一行createPdf的事。但下載環(huán)節(jié)有個(gè)坑pdfMake.createPdf(docDefinition).download(文件名.pdf)在部分瀏覽器里對(duì)中文文件名處理不一致穩(wěn)妥的做法是自己拿 blob 再走一遍a標(biāo)簽下載// 生成 PDF 并觸發(fā)下載 pdfMake.createPdf(docDefinition).getBlob((blob) { // 用 URL.createObjectURL 生成臨時(shí)地址避免中文文件名被截?cái)?const url URL.createObjectURL(blob); const link document.createElement(a); link.href url; link.download 項(xiàng)目驗(yàn)收?qǐng)?bào)告.pdf; document.body.appendChild(link); link.click(); document.body.removeChild(link); // 釋放內(nèi)存長列表導(dǎo)出多次時(shí)這步不能省 URL.revokeObjectURL(url); });getBlob的回調(diào)是異步的字體加載和排版都在這個(gè)過程中完成所以不要在回調(diào)外面假設(shè) PDF 已經(jīng)生成。revokeObjectURL這行在單次導(dǎo)出時(shí)可有可無但如果頁面上有“批量導(dǎo)出”按鈕連續(xù)點(diǎn)幾次不釋放就會(huì)累積內(nèi)存血淚經(jīng)驗(yàn)是加上。4. 從零跑起來環(huán)境、依賴與最小可運(yùn)行示例拿到一份 pdfmake 的示例代碼最怕的是依賴版本對(duì)不上、字體路徑 404。這一章按實(shí)際搭建順序走一遍確保你能在本地看到一個(gè)中文正常的 PDF。4.1 依賴安裝與版本注意pdfmake 的 npm 包和vfs_fonts是分開的兩個(gè)都要裝。版本上建議鎖同一個(gè)大版本混用容易出現(xiàn)vfs結(jié)構(gòu)不一致的問題# 安裝核心庫和內(nèi)置字體表 npm install pdfmake0.2 --save # vfs_fonts 通常隨 pdfmake 一起提供單獨(dú)引入時(shí)確認(rèn)路徑 npm install pdfmake0.2 --save如果項(xiàng)目用的是 Vite 或 Webpack 5pdfmake/build/pdfmake這個(gè)路徑一般能直接解析如果報(bào)模塊找不到檢查一下構(gòu)建工具的resolve.alias有沒有把pdfmake指到build目錄。另一個(gè)常見問題是打包后字體 URL 變成相對(duì)路徑導(dǎo)致 404這時(shí)候把字體放到public下、用絕對(duì)路徑/fonts/xxx.ttf引用最穩(wěn)。4.2 一個(gè)能直接跑的最小頁面把前面的字體注冊(cè)和文檔定義拼起來就是一個(gè)完整的最小示例。下面這段代碼可以直接放進(jìn)一個(gè) HTML 頁面或者 Vue/React 組件里import pdfMake from pdfmake/build/pdfmake; import pdfFonts from pdfmake/build/vfs_fonts; pdfMake.vfs pdfFonts.pdfMake.vfs; pdfMake.fonts { NotoSansSC: { normal: /fonts/NotoSansSC-Regular.ttf, bold: /fonts/NotoSansSC-Bold.ttf, italics: /fonts/NotoSansSC-Regular.ttf, bolditalics: /fonts/NotoSansSC-Bold.ttf } }; export function exportReport() { const docDefinition { defaultStyle: { font: NotoSansSC, fontSize: 11 }, pageMargins: [40, 60, 40, 60], content: [ { text: 導(dǎo)出測試, fontSize: 18, bold: true }, { text: 如果這行中文顯示正常說明字體注冊(cè)成功。, margin: [0, 10, 0, 0] } ] }; pdfMake.createPdf(docDefinition).getBlob((blob) { const url URL.createObjectURL(blob); const a document.createElement(a); a.href url; a.download 導(dǎo)出測試.pdf; a.click(); URL.revokeObjectURL(url); }); }跑起來之后先看兩件事一是 PDF 里中文是否正常二是控制臺(tái)有沒有字體加載失敗的 404。如果中文是方塊但控制臺(tái)沒報(bào)錯(cuò)多半是defaultStyle.font的名字和pdfMake.fonts的鍵對(duì)不上大小寫敏感NotoSansSC和notosanssc是兩個(gè)東西。4.3 驗(yàn)證導(dǎo)出結(jié)果的三個(gè)檢查點(diǎn)導(dǎo)出成功不等于導(dǎo)出正確。我一般按三個(gè)點(diǎn)驗(yàn)收第一打開 PDF 看中文和標(biāo)點(diǎn)是否完整特別是全角逗號(hào)、書名號(hào)這類容易缺字形的符號(hào)第二翻到第二頁看頁眉頁腳是否正常重復(fù)表格表頭有沒有跟著走第三用 PDF 閱讀器的“文檔屬性”看字體是否顯示為嵌入狀態(tài)。第三點(diǎn)最容易被忽略但它是判斷“換臺(tái)電腦打開會(huì)不會(huì)亂碼”的硬指標(biāo)——字體嵌入了文件到哪臺(tái)機(jī)器上顯示都一樣。5. 避坑與排查中文 PDF 導(dǎo)出最常見的五類問題這一章是我在實(shí)際項(xiàng)目里踩過的坑按“現(xiàn)象 → 原因 → 解決”整理遇到問題先對(duì)照這里查一遍能省不少時(shí)間。5.1 中文全是方塊控制臺(tái)無報(bào)錯(cuò)現(xiàn)象PDF 能生成但所有中文顯示為方塊或空白。原因defaultStyle.font引用的字體名沒有在pdfMake.fonts里注冊(cè)或者注冊(cè)了但四個(gè)樣式鍵沒給全。解決先確認(rèn)pdfMake.fonts的鍵名和defaultStyle.font完全一致再確認(rèn)normal指向的字體文件路徑在瀏覽器里能直接訪問?？梢栽谧?cè)后打印一下pdfMake.fonts看結(jié)構(gòu)對(duì)不對(duì)。5.2 字體文件 404但本地開發(fā)正?，F(xiàn)象本地npm run dev導(dǎo)出正常打包部署后中文變方塊。原因字體文件放在src/assets下被構(gòu)建工具處理成了帶哈希的路徑而代碼里寫的是固定路徑。解決把字體移到public/fonts/下用絕對(duì)路徑引用構(gòu)建工具不會(huì)改寫public下的文件路徑。這個(gè)坑我翻過兩次后來養(yǎng)成習(xí)慣凡是運(yùn)行時(shí)按 URL 加載的靜態(tài)資源一律放public。5.3 表格跨頁后表頭消失現(xiàn)象長表格翻到第二頁表頭沒了讀者不知道每列是什么。原因table定義里漏了headerRows。解決給table加上headerRows: 1如果表頭有兩行就寫2。注意這個(gè)值要和body里實(shí)際表頭行數(shù)一致寫多了會(huì)把數(shù)據(jù)行當(dāng)表頭重復(fù)。5.4 導(dǎo)出大文檔時(shí)頁面卡死現(xiàn)象幾百行表格導(dǎo)出時(shí)瀏覽器卡住幾秒甚至無響應(yīng)。原因pdfmake 在主線程做排版內(nèi)容量大了就是會(huì)阻塞。解決一是控制單次導(dǎo)出量分批生成再合并二是把生成邏輯放到 Web Worker 里主線程只負(fù)責(zé)接收 blob 和觸發(fā)下載。常見做法是超過兩百行的報(bào)表就走 Worker用戶體驗(yàn)會(huì)好很多。5.5 中文文件名下載后變成亂碼現(xiàn)象download(報(bào)告.pdf)下載下來文件名變成一串百分號(hào)編碼。原因不同瀏覽器對(duì)download屬性的中文處理不一致。解決不用庫自帶的download方法改用getBlob拿 blob 后自己創(chuàng)建a標(biāo)簽設(shè)置download現(xiàn)代瀏覽器基本都能正確處理中文文件名。6. 二次開發(fā)把導(dǎo)出邏輯抽成可配置的報(bào)表模塊示例代碼跑通之后真正要落地的是把它變成項(xiàng)目里可復(fù)用的模塊。我的做法是把“文檔定義”和“生成下載”拆開前者是一個(gè)純函數(shù)輸入業(yè)務(wù)數(shù)據(jù)、輸出docDefinition后者是一個(gè)通用工具只負(fù)責(zé)字體注冊(cè)和 blob 下載。這樣換一份報(bào)表只需要寫一個(gè)新的定義函數(shù)下載邏輯一行不用改。具體改造時(shí)我會(huì)先定義一個(gè)報(bào)表配置的接口把標(biāo)題、列定義、數(shù)據(jù)源、頁腳文案都參數(shù)化// 通用報(bào)表生成器配置驅(qū)動(dòng)避免每份報(bào)表復(fù)制粘貼 function buildReport(config) { return { defaultStyle: { font: NotoSansSC, fontSize: 10 }, pageMargins: [36, 54, 36, 54], content: [ { text: config.title, fontSize: 16, bold: true, margin: [0, 0, 0, 10] }, { table: { headerRows: 1, widths: config.columns.map(() *), // 等寬分配也可傳百分比 body: [ config.columns.map(c ({ text: c.label, bold: true })), ...config.rows.map(row config.columns.map(c String(row[c.key] ?? ))) ] } } ], footer: (page, total) ({ margin: [36, 0, 36, 0], text: ${config.footerText || } 第 ${page} 頁 / 共 ${total} 頁, alignment: right, fontSize: 8 }) }; }這段代碼的關(guān)鍵點(diǎn)是widths用map生成等寬數(shù)組body第一行是表頭、后面用展開運(yùn)算符拼數(shù)據(jù)行?? 兜住空值避免undefined被打印成字符串。改造完之后新增一份報(bào)表就是傳一個(gè)配置對(duì)象的事不用再碰字體和下載邏輯。驗(yàn)證改造是否成功我一般做兩件事一是拿一份含空字段、超長文本、跨頁表格的數(shù)據(jù)跑一遍看有沒有崩二是把生成的 PDF 用閱讀器打開檢查字體嵌入和分頁。從那以后我每次改報(bào)表配置都強(qiáng)制走一遍這兩個(gè)檢查再?zèng)]出現(xiàn)過上線后用戶反饋亂碼的情況。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取