--- theme: condensed-night-purple highlight: atom-one-dark-reasonable --- ### 前言业务需要将页面导出为pdf，并尽可能保证模块在分页时不被切割，所以分享一下踩坑的过程 ### 客户端导出PDF **优点：** 1. **资源节省**：不需要服务器处理，减少了服务器负担，用户的浏览器直接生成PDF。 2. **即时反馈**：用户可以快速看到生成的结果，适合小型文档或简单内容的导出。 3. **易于实现**：使用库如`html2canvas`和`jsPDF`，可以快速实现导出功能，代码量较少。 **缺点：** 1. **性能限制**：受限于用户的浏览器性能，处理复杂文档时可能会出现卡顿。 2. **兼容性问题**：不同浏览器对CSS和字体的支持不一致，可能导致PDF格式不一致或乱码。 3. **功能限制**：对于复杂的布局和样式，可能无法完全还原，尤其是涉及动态内容时。 ### 服务器端导出PDF **优点：** 1. **强大的处理能力**：服务器通常有更强的计算能力，可以处理复杂的文档和大量数据。 2. **一致性**：生成的PDF格式在不同设备和浏览器上保持一致，避免了客户端的兼容性问题。 3. **灵活性**：可以使用如`Puppeteer`等工具，支持更复杂的样式和布局，甚至可以在生成PDF前进行数据处理。 **缺点：** 1. **资源消耗**：服务器需要处理PDF生成请求，可能增加服务器负担，尤其是在高并发情况下。 2. **延迟**：用户需要等待服务器处理完成，可能导致体验不如客户端即时。 3. **实现复杂性**：需要设置服务器环境和处理请求，开发和维护成本较高 ### 客户端导出这里引用一篇文章： ### 服务端导出 #### 核心能力 > 基于pupeteer，那pupeteer是什么？ > Puppeteer 是一个 Node 库，它提供了一个高级 API 来通过 DevTools 协议控制 Chromium 或 Chrome 浏览器。它默认以无头（headless）模式运行，但也可以配置为在可见（"有头"）浏览器中运行。使用 Puppeteer，你可以实现几乎所有在浏览器中手动执行的操作，例如： > > * 自动提交表单、UI 测试、键盘输入等； > * 创建自动化测试环境，使用最新的 JavaScript 和浏览器功能； > * 捕获网站的 timeline trace 以帮助分析性能问题； > * 测试 Chrome 扩展程序； > * 生成页面的屏幕截图和 PDF； > * 抓取 SPA（单页应用）并生成预渲染内容（即 "SSR"（服务器端渲染）） #### 开发一个简单版接口步骤1：基于koa搭建http服务 ```js ... const Koa = require('koa') const Router = require('koa-router') const http = require('http') const app = new Koa() const router = new Router(); router.get('/export/pdf', async (ctx) => { await createPdf({ hostname: ctx.hostname, id: ctx.query.id, type: ctx.query.type, token: ctx.query.token }); let filePath = './page.pdf' let file = fs.createReadStream(filePath) let fileName = filePath.split('\').pop() ctx.set('Content-disposition', 'attachment;filename=' + encodeURIComponent(fileName)) ctx.set('Content-type', 'application/pdf') ctx.body = file }); app.use(router.routes()).use(router.allowedMethods()) http.createServer(app.callback()).listen(9527); ``` 步骤2：调用pupeteer实现导出 ```js async function createPdf(obj) { const browser = await puppeteer.launch(); const page = await browser.newPage(); await page.setBypassCSP(false); await page.setExtraHTTPHeaders({ Authorization: "Bearer " + obj.token, }); await page .mainFrame() .goto(`http://${obj.hostname}:3002/exportReport?id=${obj.id}&type=${obj.type}`, { waitUntil: ["networkidle2"], }); // await page.reload({ timeout: 60000, waitUntil: ['networkidle2'] }) await page.pdf({ path: "page.pdf", displayHeaderFooter: false, footerTemplate: "

pdf测试

", format: "A4", preferCSSPageSize: false, printBackground: true, margin: { top: "20", bottom: "20", }, }); // page.close() browser.close(); } ``` 基于以上逻辑，即可完成简单的导出pdf #### 用于生产环境的服务 * 如果对业务稳定性，性能没有要求：通过以上单文件的方式+pm2的方式即可部署 * 考虑到后期利用pupeteer的其他能力，以及服务稳定性，所以考虑使用成熟的基于koa的框架，最终选型egg ##### 遇到的问题 ###### 1.如何解决打开客户端提供的url时，依赖的接口鉴权问题？解决办法有两种： 1. 方式一：将url中依赖的接口设置为白名单（不鉴权） 2. 方式二：客户端提供url时，携带接口鉴权的信息，通过pupeteer的api完成设置 ```js ... const browser = await puppeteer.launch({}); const page = await browser.newPage(); await page.setExtraHTTPHeaders({ ['token']: 'xxxxxx', }); ``` ###### 2.pupeteer打开客户端提供的url时，如何判断整个页面已经渲染完成？使用goto方法时，官方提供了如下等待方式 ```js export type PuppeteerLifeCycleEvent = /** * Waits for the 'load' event. */ | 'load' /** * Waits for the 'DOMContentLoaded' event. */ | 'domcontentloaded' /** * Waits till there are no more than 0 network connections for at least `500` * ms. */ | 'networkidle0' /** * Waits till there are no more than 2 network connections for at least `500` * ms. */ | 'networkidle2'; ``` 设置"domcontentloaded"时发现导出的pdf模块数据缺失，单页应用中，此事件只会触发一次，不适用于打开url时有路由跳转； *这里改用由客户端业务侧来控制完成标识* * 步骤1：客户端调用依赖的接口数据后，设置完成标识，调用接口时将标识告诉服务端 ```js flag=false; async getData() { await api1(); await api2(); ... nextTick(()=>{ flag=true; }) } ``` * 步骤2：服务端接收到完成标识后，等待元素出现则认为页面渲染完成 ```js const browser = await puppeteer.launch({}); const page = await browser.newPage(); await page.setExtraHTTPHeaders({ ['token']: 'xxxxxx', }); // 打开url await page.mainFrame().goto(fullUrl); // 等待渲染成功的标识元素出现 await page.waitForSelector(completeTag); ``` ###### 3.导出的pdf中图片或者其他模块被切割的问题？基于CSS中的属性`page-break-after`、`page-break-before`和`page-break-inside` 1. `page-break-before`属性： * 定义：指定在元素之前是否应该插入分页符。 * 可能的值： * `auto`：由浏览器决定是否在元素前进行分页。 * `always`：总是在元素前进行分页。 * `avoid`：避免在元素前进行分页。 * `left`：如果元素在页面的左侧，则总是在元素前进行分页。 * `right`：如果元素在页面的右侧，则总是在元素前进行分页。 2. `page-break-after`属性： * 定义：指定在元素之后是否应该插入分页符。 * 可能的值与`page-break-before`相同。 3. `page-break-inside`属性： * 定义：指定元素内部的内容是否允许在分页时被分割到不同的页面上。 * 可能的值： * `auto`：由浏览器决定元素内部内容是否可以跨页。 * `avoid`：避免将元素内部的内容分割到不同的页面上。在实际应用中，这些属性可以帮助你控制页面的布局，尤其是在打印长文档或创建PDF文件时，确保内容的连续性和格式的正确性。例如，如果你不希望一个图片或表格被分割到两页上，可以在该元素上使用`page-break-inside: avoid;`来避免这种情况代码示例： ```js // 元素child1会在它之前插入分页符 // 元素child2会在它之后插入分页符 // 元素child3内部不允许插入换行符（内容不能超过一页，当前页放不下，自动换到下一页） // css中可以通过如下方式设置打印样式 @media print { table tr { page-break-inside: avoid !important; // tr不能被分割 } thead { display: table-header-group !important; // 分页后每一页都有表头 } } } } ``` ###### 4.服务如何在不同项目中部署复用？如果项目A，项目B（内网部署的项目）等等都需要该导出pdf的服务，如何复用呢？当然是将服务docker化，然后集成到CI/CD流程中；上Dockerfile脚本： ```js # 使用官方的 Node.js 镜像作为基础镜像 FROM node:20.15.0-slim # Install latest chrome dev package and fonts to support major charsets (Chinese, Japanese, Arabic, Hebrew, Thai and a few others) # Note: this installs the necessary libs to make the bundled version of Chrome for Testing that Puppeteer # installs, work. RUN apt-get update \ && apt-get install -y wget gnupg \ && wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | apt-key add - \ && sh -c 'echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google.list' \ && apt-get update \ && apt-get install -y google-chrome-stable fonts-ipafont-gothic fonts-wqy-zenhei fonts-thai-tlwg fonts-kacst fonts-freefont-ttf libxss1 \ --no-install-recommends \ && rm -rf /var/lib/apt/lists/* # 创建工作目录 RUN mkdir -p /home/app RUN mkdir -p /home/etahadmin # 挂在路径 VOLUME /home/etahadmin # 设置工作目录 WORKDIR /home/app # 将 package.json 和 package-lock.json 复制到工作目录 COPY package*.json ./ # 安装依赖 RUN npm install --registry=https://registry.npmmirror.com/ # 将所有文件复制到工作目录 COPY . /home/app # 暴露端口 EXPOSE 7001 # 启动应用 CMD ["npm", "run", "start"] ``` ##### 导出pdf时会生成临时文件，何时删除？ * 如果不清理这些临时文件，则垃圾文件会越来越多 * 清理策略：每日凌晨删除前一天产生的文件 egg的schedule模块： daily\_task.js ```js const Subscription = require('egg').Subscription; const fileHelper = require('../extend/fileHelper'); const dateHelper = require('../extend/date'); class DailyTask extends Subscription { // 通过 schedule 属性来设置定时任务的执行间隔等配置 static get schedule() { return { // interval: '1m', // 1 分钟间隔 cron: '0 2 * * *', // 凌晨执行 type: 'worker', // 某一个 worker执行 }; } // subscribe 是真正定时任务执行时被运行的函数 async subscribe() { // 删除前一天的 const prevDay = dateHelper.addSpecificDate(null, 0); fileHelper.deleteDirectory(fileHelper.join(this.app.config.tempPathName, prevDay)); } } module.exports = DailyTask; ``` ##### api完整代码实现 1. 初始化框架 ```js npm init egg --type=simple ``` 目录结构： ![project-dir-list.jpg](https://p3-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/3bd948959e5b42ca82ac4a40d238d575~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAgU3lubWJyZg==:q75.awebp?rk3s=f64ab15b&x-expires=1772682575&x-signature=yMgwEk3TdYTdBl6MLKrK2yGNuEk%3D) 2. 定义路由 ```js /** * @param {Egg.Application} app - egg application */ module.exports = app => { const { router, controller } = app; router.get('/', controller.home.index); router.get('/api/generatePdf', controller.api.index); }; ``` 3. 开发api ```js const { Controller } = require('egg'); const fileHelper = require('../extend/fileHelper'); class ApiController extends Controller { async index() { const { ctx } = this; const fullUrl = ctx.query.fullUrl;// 完成url，包含id等信息 const friendlyName = ctx.query.friendlyName || '';// 友好名，用于下载 const authKey = ctx.query.authKey || ''; // 需要设置的请求头 const authValue = ctx.query.authValue || ''; // 需要设置的请求头 const completeTag = ctx.query.completeTag || '.is-rendered-tag'; const config = ctx.config || {}; // 其他配置项 let error = ''; // 验证 if (!fullUrl) { error = 'fullUrl is required'; } if (!completeTag) { error = 'completeTag is required'; } if (error) { ctx.body = error; return false; } // 根据当前请求生成文件名 const { filePath, uniqueName } = ctx.service.api.generateFileNameAndPath(this.app.config.tempPathName, fullUrl); // 生成pdf await ctx.service.api.createPdf({ fullUrl, filePath, authKey, authValue, completeTag, config, }); // 读取文件流 const file = fileHelper.readStream(filePath); ctx.set('Content-disposition', 'attachment;filename=' + encodeURIComponent(friendlyName ? friendlyName : uniqueName)); ctx.set('Content-type', 'application/pdf'); ctx.body = file; } } module.exports = ApiController; ``` ##### service层完整代码实现 ```js const Service = require('egg').Service; const stringHelper = require('../extend/string'); const fileHelper = require('../extend/fileHelper'); const dateHelper = require('../extend/date'); const puppeteer = require('puppeteer'); class ApiService extends Service { // 生成名称 generateFileNameAndPath(tempPath, fullUrl) { const ext = '.pdf'; // 根据当前请求生成文件名 let uniqueName = stringHelper.md5(fullUrl); const timePath = dateHelper.formatDateTime(dateHelper.getCurrentTimeInt(false), dateHelper.FORMAT_TYPE.TYPE_YMD); // 当前路径 const currentPath = fileHelper.join(tempPath, timePath); fileHelper.createDirectory(currentPath); const filenameWithExt = `${uniqueName}${ext}`; const filePath = fileHelper.join(currentPath, filenameWithExt); return { uniqueName: filenameWithExt, filePath }; } // 生成pdf async createPdf(pdfParams = {}) { const { fullUrl, filePath, authKey, authValue, completeTag, config } = pdfParams; // 是否有footer const footerTip = config?.footerTip || 'pdf测试'; const margin = config.margin || 20; const browser = await puppeteer.launch({ args: [ '--ignore-certificate-errors', // 忽略证书错误 '--no-sandbox', ], }); const page = await browser.newPage(); // await page.setBypassCSP(false); if (authKey && authValue) { await page.setExtraHTTPHeaders({ [`${authKey}`]: authValue, }); } // 打开url await page.mainFrame().goto(fullUrl); // 等待渲染成功的标识元素出现 await page.waitForSelector(completeTag); // 导出pdf await page.pdf({ path: filePath, displayHeaderFooter: false, footerTemplate: `

${footerTip}

`, format: 'A4', preferCSSPageSize: false, printBackground: true, margin: { top: `${margin}`, bottom: `${margin}`, }, }); // page.close() await browser.close(); } } module.exports = ApiService; ``` #### 优化 ###### 1.如何提高接口的响应速度 * 节省launch时间（见如何支持更多并发） * 加缓存伪代码实现 ```js ... // 需要导出的url const fullUrl = ctx.query.fullUrl;// 完成url，包含id等信息 // 根据url生成一个唯一key，作为pdf文件名 const md5Key = md5(fullUrl); // 检查文件是否存在 const flag = fs.fileExistsSync(`${filePath}/${md5Key}.pdf`); if(flag) { // 直接返回缓存的文件 } else { // 1.调用pupeteer生成pdf文件 // 2.直接返回缓存的文件 } ``` 缓存效果对比： ![缓存对比时间.jpg](https://p3-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/fd425a3487944a53baf5a7cae36a335f~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAgU3lubWJyZg==:q75.awebp?rk3s=f64ab15b&x-expires=1772682575&x-signature=SuVYGhxxQ15TYxgpHn1pOss0m1k%3D) ###### 2.如何支持更多并发 1. 写一个链接池的类 genericPool.js 2. 在程序启动时，初始化连接池 3. 从连接池获取实例 ```js ... // 写一个链接池的类 genericPool.js // 写一个链接池的类 genericPool.js function initPuppeteerPool() { const factory = { create: () => puppeteer.launch(puppeteerArgs).then(instance => { // 创建一个 puppeteer 实例，并且初始化使用次数为 0 instance.useCount = 0; return instance; }), destroy: instance => { instance.close(); }, validate: instance => { // 执行一次自定义校验，并且校验校验实例已使用次数。当返回 reject 时表示实例不可用 return validator(instance).then(valid => Promise.resolve(valid && (maxUses <= 0 || instance.useCount < maxUses))); }, }; const pool = genericPool.createPool(factory, config); const genericAcquire = pool.acquire.bind(pool); pool.acquire = () => genericAcquire().then(instance => { instance.useCount += 1; return instance; }); pool.use = fn => { let resource; return pool .acquire() .then(r => { resource = r; return resource; }) .then(fn) .then( result => { // 不管业务方使用实例成功与后都表示一下实例消费完成 pool.release(resource); return result; }, err => { pool.release(resource); throw err; } ); }; return pool; } // 生命周期中启用以及销毁 const initPuppeteerPool = require('./app/extend/genericPool'); class AppBootHook { constructor(app) { this.app = app; } async didLoad() { // 所有的配置已经加载完毕 // 可以用来加载应用自定义的文件，启动自定义的服务 this.app.pool = initPuppeteerPool({ puppeteerArgs: { args: [ '--ignore-certificate-errors', // 忽略证书错误 '--no-sandbox', ], }, }); } async beforeClose() { // 释放资源 if (this.app.pool.drain) { await this.app.pool.drain().then(() => this.app.pool.clear()); } } } // service层 createPdf() { // 从链接池中取出实例 await this.app.pool.use(async instance => { // 取出连接后直接就是newPage，节省了lanuch时间 const page = await instance.newPage(); ... }) } ``` ### 完整代码见如下git仓库： [yc-lm/document-helper (github.com)](https://github.com/yc-lm/document-helper) ### 参考文档 1. 2. [Puppeteer (pptr.dev)](https://pptr.dev/guides/what-is-puppeteer)