實踐指南-網頁生成PDF

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

一、背景

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

二、技術選型

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

1. Puppeteer

Puppeteer 是一個 Node 庫,它提供了高階 API 來通過 DevTools 協議控制 ChromeChromium

在瀏覽器中手動執行的大多數操作都可以使用 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-corepuppeteer 的輕量級版本,預設不下載瀏覽器,而是啟動現有的瀏覽器或者連線遠端瀏覽器,使用 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,注意除 namevalue外,expiresdomainpath 也需要配置。

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),不定時推送文章:

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

相關文章