實踐指南-網頁生成PDF

凹凸實驗室發表於2021-06-03
網頁

一、背景

開發工作中，需要實現網頁生成 PDF 的功能，生成的 PDF 需上傳至服務端，將 PDF 地址作為引數請求外部介面，這個轉換過程及轉換後的 PDF 不需要在前端展示給使用者。

二、技術選型

該功能不需要在前端展示給使用者，為節省客戶端資源，選擇在服務端實現網頁生成 PDF 的功能。

1. Puppeteer

Puppeteer 是一個 Node 庫，它提供了高階 API 來通過 DevTools 協議控制 Chrome 或 Chromium。

在瀏覽器中手動執行的大多數操作都可以使用 Puppeteer 完成，比如：

  • 生成頁面的螢幕截圖和 PDF；
  • 爬取 SPA 並生成預渲染的內容（即 SSR）；
  • 自動進行表單提交，UI 測試，鍵盤輸入等；
  • 建立最新的自動化測試環境。使用最新的 JavaScript 和瀏覽器功能，直接在最新版本的 Chrome 中執行測試；
  • 捕獲時間線跟蹤網站，以幫助診斷效能問題；
  • 測試 Chrome 擴充套件程式。

從上可見，Puppeteer 可以實現在Node 端生成頁面的 PDF 功能。

三、實現步驟

1. 安裝

進入專案，安裝 puppeteer 到本地。

$ npm install -g cnpm --registry=https://registry.npm.taobao.org
$ cnpm i puppeteer --save

需注意的是，安裝 puppeteer 時，會下載與 API 一起使用的最新版本的 Chromium 瀏覽器，有以下方法可以修改預設設定，不下載瀏覽器：

  1. 在環境變數中設定 PUPPETEER_SKIP_CHROMIUM_DOWNLOAD；
  2. 用 puppeteer-core 代替 puppeteer。

puppeteer-core 是 puppeteer 的輕量級版本，預設不下載瀏覽器，而是啟動現有的瀏覽器或者連線遠端瀏覽器，使用 puppeteer-core 需注意本地有可連線的瀏覽器，且安裝的 puppeteer-core 版本與打算連線的瀏覽器相容。連線本地瀏覽器方法如下：

const browser = await puppeteer.launch({ 
  executablePath: '/path/to/Chrome' 
});

本專案需要部署至服務端，沒有可連線的瀏覽器，因此選擇安裝的是 puppeteer。

2. 啟動瀏覽器

const browser = await puppeteer.launch({
    headless: true,
    args: ['--no-sandbox', '--font-render-hinting=medium']
  })

headless 代表無頭模式，在後端啟動瀏覽器，前端不會有展示。

小建議：本地除錯時，建議設定 headless: false，可以啟動完整版本的瀏覽器，直接在瀏覽器視窗檢視內容。

3. 開啟新頁面

生成瀏覽器後，在瀏覽器中開啟新頁面。

const page = await browser.newPage()

4. 跳轉到指定頁面

跳轉至要生成 PDF 的頁面。

await page.goto(`${baseURL}/article/${id}`, {
    timeout: 60000,
    waitUntil: 'networkidle2', // networkidle2 會一直等待，直到頁面載入後不存在 2 個以上的資源請求，這種狀態持續至少 500 ms
  })

timeout 是最長的載入時間，預設 30s，網頁載入時間長的情況下，建議將 timeout 值改大，防止超時報錯。

waitUntil 表示頁面載入到什麼程度可以開始生成 PDF 或其他操作了，當網頁需載入的圖片資源較多時，建議設定為 networkidle2，有以下值可選：

  • load：當 load 事件觸發時；
  • domcontentloaded： 當 DOMContentLoaded 事件觸發時；
  • networkidle0： 頁面載入後不存在 0 個以上的資源請求，這種狀態持續至少 500 ms；
  • networkidle2： 頁面載入後不存在 2 個以上的資源請求，這種狀態持續至少 500 ms。

5. 指定路徑，生成pdf

上述指定的頁面載入完成後，將該頁面生成 PDF。

  const ext = '.pdf'
  const key = randomFilename(title, ext)
  const _path = path.resolve(config.uploadDir, key)
  await page.pdf({ path: _path, format: 'a4' })

path 表示將 PDF 儲存到的檔案路徑，如果未提供路徑，PDF 將不會儲存至磁碟。

小建議：不管 PDF 是不是需要儲存到本地，建議在除錯的時候都設定一個path，方便檢視生成的 PDF 的樣式，檢查是否有問題。

format 表示 PDF 的紙張格式，a4 尺寸為 8.27 英寸 x 11.7 英寸，是傳統的列印尺寸。

注意：目前僅支援headless: true 無頭模式下生成 PDF

6. 關閉瀏覽器

所有操作完成後，關閉瀏覽器，節約效能。

  await browser.close()

四、難點

1. 圖片懶載入

由於需生成 PDF 的頁面是文章型別的頁面，包含大量圖片，且圖片引入了懶載入，導致生成的 PDF 會帶有很多懶載入兜底圖，效果如下圖：

解決方法是跳轉到頁面後，將頁面滾動到底部，所有圖片資源都會得到請求，waitUntil 設定為 networkidle2，圖片就能載入成功了。

await autoScroll(page) // 因為文章圖片引入了懶載入，所以需要把頁面滑動到最底部，保證所有圖片都載入出來

/**
 * 控制頁面自動滾動
 * */
function autoScroll (page) {
  return page.evaluate(() => {
    return new Promise<void>(resolve => {
      let totalHeight = 0
      const distance = 100
      // 每200毫秒讓頁面下滑100畫素的距離
      const timer = setInterval(() => {
        const scrollHeight = document.body.scrollHeight
        window.scrollBy(0, distance)
        totalHeight += distance
        if (totalHeight >= scrollHeight) {
          clearInterval(timer)
          resolve()
        }
      }, 200)
    })
  })
}

這裡用到了 page.evaluate() 方法，用來控制頁面操作，比如使用內建的 DOM 選擇器、使用 window 方法等等。

2. CSS 列印樣式

根據官網說明，page.pdf() 生成 PDF 檔案的樣式是通過 print css media 指定的，因此可以通過 css 來修改生成的 PDF 的樣式，以本文需求為例，生成的 PDF 需要隱藏頭部、底部，以及其他和文章主體無關的部分，程式碼如下：

@media print {
  .other_info,
  .authors,
  .textDetail_comment,
  .detail_recTitle,
  .detail_rec,
  .SuspensePanel {
    display: none !important;
  }

  .Footer,
  .HeaderSuctionTop {
    display: none;
  }
}

3. 登入態

由於存在一部分文章不對外部使用者公開，需要鑑權使用者身份，符合要求的使用者才能看到文章內容，因此跳轉到指定文章頁後，需要在生成的瀏覽器視窗中注入登入態，符合條件的登入使用者才能看到這部分文章的內容。

採用注入 cookie 的方式來獲取登入態，使用 page.evaluate() 設定 cookie，程式碼如下：


async function simulateLogin (page, cookies, domain) {
  return await page.evaluate((sig, sess, domain) => {
    let date = new Date()
    date = new Date(date.setDate(date.getDate() + 1))
    let expires = ''
    expires = `; expires=${date.toUTCString()}`
    document.cookie = `koa:sess.sig=${sig}${expires}; domain=${domain}; path=/`
    document.cookie = `koa:sess=${sess}=${expires}; domain=${domain}; path=/` // =是這個cookie的value
    document.cookie = `is_login=true${expires}; domain=${domain}; path=/`
  }, cookies['koa:sess.sig'], cookies['koa:sess'], domain)
}


await simulateLogin(page, cookies, config.domain.split('//')[1])

小建議：Puppeteer 也有自帶的 api 實現 cookie 注入，如 page.setCookie({name: name, value: value})，但是我用這個方式注入沒能獲取到登入態，沒有找到具體原因，建議還是直接用我上面這個方法來注入 cookie，注意除 name 和 value外，expires、domain、path 也需要配置。

4. Docker 部署 Puppeteer

根據上文操作，本地已經可以成功將頁面生成 PDF 了，本地體驗沒問題後，需要部署到服務端給到測試、上線。

沒有修改 Dockerfile 時，部署後發現瞭如下錯誤：

官網有給 Docker 配置說明可以參考，最終實踐可用的 ubuntu 系統的 Dockerfile 如下：

# ...省略...

# 安裝 puppeteer 依賴
RUN apt-get update && \
    apt-get install -y libgbm-dev && \
    apt-get install gconf-service libasound2 libatk1.0-0 libatk-bridge2.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgcc1 libgconf-2-4 libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 ca-certificates fonts-liberation libappindicator1 libnss3 lsb-release xdg-utils wget build-essential libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev -y && \
    apt-get install -y fonts-ipafont-gothic fonts-wqy-zenhei fonts-thai-tlwg fonts-kacst fonts-freefont-ttf --no-install-recommends

# ...省略...

只需要重點關注 安裝 puppeteer 依賴 部分即可。

注意：在 v1.18.1 之前，Puppeteer 至少需要 Node v6.4.0。從 v1.18.1 到 v2.1.0 的版本都依賴於 Node 8.9.0+。從 v3.0.0 開始，Puppeteer 開始依賴於 Node 10.18.1+。配置 Dockerfile 時也需要注意服務端的 node 版本。

五、總結

本文講述了實現在 Node 端將網頁生成 PDF 檔案的完整過程，總結為以下 3 點：

  1. 技術選型，根據需求場景選擇合適的手段實現功能；
  2. 閱讀官方文件，快速過一遍文件才能少遇到些坑；
  3. 破解難點，使用一個未使用的工具，會遇到沒有解決過的難題，遇招拆招吧 ^ ^。

參照 Demo 原始碼 可快速上手上述功能，希望本文能對你有所幫助，感謝閱讀❤️

· 往期精彩 ·

【直播回顧·程式媛的成長蛻變】

【大規格檔案的上傳優化】

【JDR DESIGN 開發小結】

歡迎關注凹凸實驗室部落格：aotu.io

或者關注凹凸實驗室公眾號（AOTULabs），不定時推送文章：

歡迎關注凹凸實驗室公眾號

相關文章