1. 從“一行命令”到“一鍵生成”P(pán)laywright PDF 轉(zhuǎn)換的吸引力最近在社區(qū)里看到不少開(kāi)發(fā)者都在討論一個(gè)聽(tīng)起來(lái)很“酷”的功能用 Playwright 一行命令就能把 HTML 網(wǎng)頁(yè)保存為 PDF。這個(gè)標(biāo)題本身就充滿了吸引力——“牛”、“一行命令”、“一鍵”、“太方便了”。作為一個(gè)長(zhǎng)期和網(wǎng)頁(yè)自動(dòng)化、文檔生成打交道的開(kāi)發(fā)者我完全理解這種興奮感。它戳中了我們幾個(gè)核心痛點(diǎn)手動(dòng)打印網(wǎng)頁(yè)為 PDF 格式混亂、需要處理復(fù)雜的 CSS 分頁(yè)、或者依賴服務(wù)器端渲染服務(wù)。Playwright 這個(gè)現(xiàn)代瀏覽器自動(dòng)化工具似乎提供了一個(gè)近乎完美的本地解決方案。但“一行命令”背后真的那么簡(jiǎn)單嗎在實(shí)際項(xiàng)目中我們需要的往往不是一次性的轉(zhuǎn)換而是穩(wěn)定、可靠、且輸出質(zhì)量可控的批量文檔生成。Playwright 的page.pdf()方法確實(shí)強(qiáng)大它本質(zhì)上是在用無(wú)頭瀏覽器Headless Browser加載并渲染頁(yè)面然后調(diào)用瀏覽器的打印功能生成 PDF。這比簡(jiǎn)單的 HTML 轉(zhuǎn) PDF 庫(kù)如 wkhtmltopdf優(yōu)勢(shì)明顯因?yàn)樗芡昝乐С脂F(xiàn)代 CSS3、Flexbox、Grid 布局甚至是復(fù)雜的 JavaScript 交互和動(dòng)態(tài)加載的內(nèi)容。然而從“能跑通”到“產(chǎn)出符合要求的商業(yè)文檔”中間還有很長(zhǎng)的路要走。這篇文章我就結(jié)合自己多次將 Playwright 用于生產(chǎn)環(huán)境 PDF 生成的經(jīng)驗(yàn)拆解這“一行命令”背后的門(mén)道。我們會(huì)從環(huán)境搭建、核心命令解析開(kāi)始然后深入到實(shí)際應(yīng)用中最關(guān)鍵的幾個(gè)環(huán)節(jié)如何確保樣式一致性、如何處理分頁(yè)和頁(yè)眉頁(yè)腳、如何應(yīng)對(duì)異步加載內(nèi)容以及如何構(gòu)建一個(gè)健壯的批量轉(zhuǎn)換腳本。你會(huì)發(fā)現(xiàn)最初的“一行命令”只是一個(gè)起點(diǎn)真正的價(jià)值在于如何基于它構(gòu)建一個(gè)可靠的工作流。2. 環(huán)境準(zhǔn)備與核心命令全解在開(kāi)始“一鍵轉(zhuǎn)換”之前我們需要一個(gè)可用的 Playwright 環(huán)境。很多人卡在第一步因?yàn)?Playwright 不是普通的 Python 庫(kù)它需要安裝特定的瀏覽器二進(jìn)制文件。2.1 安裝與瀏覽器管理首先通過(guò) pip 安裝 Playwright 的 Python 版本pip install playwright安裝完庫(kù)之后最關(guān)鍵的一步是安裝瀏覽器。Playwright 支持 Chromium、Firefox 和 WebKit。對(duì)于 PDF 生成我強(qiáng)烈推薦使用 Chromium因?yàn)樗诖蛴邮街С趾头€(wěn)定性上通常表現(xiàn)最好。運(yùn)行以下命令來(lái)安裝 Chromiumplaywright install chromium這個(gè)命令會(huì)下載 Chromium 瀏覽器到你的本地緩存中。這里有個(gè)細(xì)節(jié)需要注意Playwright 管理的瀏覽器是特定版本的與你自己安裝的 Chrome 無(wú)關(guān)。這保證了運(yùn)行環(huán)境的一致性避免了因?yàn)g覽器版本不同導(dǎo)致的渲染差異。如果你需要在一個(gè)無(wú) GUI 的服務(wù)器如 Linux 服務(wù)器上運(yùn)行記得系統(tǒng)可能需要安裝一些額外的依賴庫(kù)例如libnss3、libatk-bridge2.0等。Playwright 的安裝腳本通常會(huì)提示如果遇到問(wèn)題查閱官方文檔的“系統(tǒng)依賴”部分是最快的解決方式。2.2 剖析那“一行命令”現(xiàn)在讓我們看看傳說(shuō)中的“一行命令”在代碼里是什么樣子。一個(gè)最基礎(chǔ)的版本如下import asyncio from playwright.async_api import async_playwright async def main(): async with async_playwright() as p: browser await p.chromium.launch() page await browser.new_page() await page.goto(https://example.com) await page.pdf(pathoutput.pdf) await browser.close() asyncio.run(main())如果使用同步 API代碼更緊湊from playwright.sync_api import sync_playwright with sync_playwright() as p: browser p.chromium.launch() page browser.new_page() page.goto(https://example.com) page.pdf(pathoutput.pdf) browser.close()這確實(shí)可以稱(chēng)為“一行”核心命令page.pdf(pathoutput.pdf)。但它的威力遠(yuǎn)不止于此。page.pdf()方法接受一個(gè)字典參數(shù)用于精細(xì)控制輸出的 PDF。下面是一些最常用且至關(guān)重要的參數(shù)path: 輸出文件路徑。如果不指定則 PDF 內(nèi)容會(huì)以字節(jié)形式返回方便你進(jìn)行網(wǎng)絡(luò)傳輸或進(jìn)一步處理。format: 紙張格式如 ‘A4’, ‘Letter’, ‘Legal’。默認(rèn)為 ‘Letter’。這里第一個(gè)坑就來(lái)了如果你要生成中文文檔或者有嚴(yán)格的版面要求務(wù)必明確設(shè)置format。國(guó)際標(biāo)準(zhǔn) A4 和美國(guó)信紙 Letter 的尺寸是不同的。scale: 縮放比例默認(rèn)為 1。你可以通過(guò)調(diào)整它來(lái)放大或縮小內(nèi)容在 PDF 中的呈現(xiàn)。print_background: 布爾值是否打印背景圖形和顏色。默認(rèn)是False。這意味著如果你的網(wǎng)頁(yè)有漂亮的背景色或背景圖生成的 PDF 很可能是一片白色。99% 的情況下你需要將其設(shè)為T(mén)rue。margin: 設(shè)置頁(yè)邊距。可以是一個(gè)包含top,right,bottom,left字段的字典也可以是像‘1cm’這樣的統(tǒng)一字符串。合理的邊距是生成專(zhuān)業(yè)文檔的基礎(chǔ)。display_header_footer: 布爾值是否顯示頁(yè)眉頁(yè)腳。開(kāi)啟后你需要通過(guò)注入 CSS 或利用頁(yè)面內(nèi)特定的div來(lái)定義頁(yè)眉頁(yè)腳的內(nèi)容這部分我們后面會(huì)詳細(xì)講。header_template/footer_template: 當(dāng)display_header_footer為T(mén)rue時(shí)用于定義頁(yè)眉頁(yè)腳的 HTML 模板字符串。這是實(shí)現(xiàn)自定義頁(yè)碼、日期、標(biāo)題的關(guān)鍵。一個(gè)更接近生產(chǎn)可用的命令可能長(zhǎng)這樣page.pdf( pathreport.pdf, formatA4, print_backgroundTrue, margin{top: 2cm, right: 1.5cm, bottom: 2cm, left: 1.5cm}, display_header_footerTrue, header_templatediv stylefont-size: 10px; text-align: center; width: 100%;span classtitle/span/div, footer_templatediv stylefont-size: 9px; text-align: center; width: 100%;第 span classpageNumber/span 頁(yè)共 span classtotalPages/span 頁(yè)/div )3. 跨越理想與現(xiàn)實(shí)樣式、布局與內(nèi)容捕獲的實(shí)戰(zhàn)難題當(dāng)你用上面的“增強(qiáng)版”一行命令去轉(zhuǎn)換一個(gè)稍微復(fù)雜點(diǎn)的網(wǎng)頁(yè)時(shí)大概率會(huì)遇到各種問(wèn)題布局錯(cuò)亂、圖片不顯示、分頁(yè)位置詭異、頁(yè)眉頁(yè)腳沒(méi)出來(lái)。這才是實(shí)戰(zhàn)的開(kāi)始。3.1 確保樣式完整渲染等待與模擬網(wǎng)頁(yè)不是靜態(tài)的。現(xiàn)代前端應(yīng)用大量使用 JavaScript 動(dòng)態(tài)加載內(nèi)容、渲染圖表、執(zhí)行動(dòng)畫(huà)。如果頁(yè)面還沒(méi)加載完就執(zhí)行page.pdf()生成的 PDF 可能缺少關(guān)鍵部分。策略一主動(dòng)等待導(dǎo)航與網(wǎng)絡(luò)空閑page.goto()方法會(huì)等待頁(yè)面觸發(fā)load事件但這對(duì)于單頁(yè)應(yīng)用SPA或異步加載內(nèi)容往往不夠。更可靠的方法是結(jié)合wait_until參數(shù)# 等待到網(wǎng)絡(luò)幾乎空閑至少500ms內(nèi)沒(méi)有超過(guò)2個(gè)網(wǎng)絡(luò)請(qǐng)求 await page.goto(‘https://example.com/dashboard‘, wait_until‘networkidle‘)networkidle在大部分情況下是安全的。但對(duì)于一些輪詢請(qǐng)求的頁(yè)面可能需要使用wait_for_selector等待某個(gè)代表內(nèi)容加載完成的關(guān)鍵元素出現(xiàn)await page.goto(‘https://example.com‘) await page.wait_for_selector(‘.data-table-loaded‘) # 等待數(shù)據(jù)表格加載完成策略二處理懶加載與滾動(dòng)對(duì)于需要滾動(dòng)才能加載的內(nèi)容如圖片懶加載你需要在生成 PDF 前模擬滾動(dòng)確保所有內(nèi)容都被觸發(fā)渲染。一個(gè)簡(jiǎn)單粗暴但有效的方法是滾動(dòng)到頁(yè)面底部await page.evaluate(‘window.scrollTo(0, document.body.scrollHeight)‘) await page.wait_for_timeout(1000) # 給懶加載內(nèi)容一點(diǎn)時(shí)間策略三注入打印樣式屏幕樣式screen和打印樣式print是不同的 CSS 媒體類(lèi)型。網(wǎng)頁(yè)可能沒(méi)有定義打印樣式導(dǎo)致 PDF 布局混亂。我們可以在生成 PDF 前向頁(yè)面注入針對(duì)打印優(yōu)化的 CSSprint_style “““ media print { body { font-size: 12pt; } .sidebar { display: none !important; } /* 隱藏不需要打印的側(cè)邊欄 */ .page-break { page-break-before: always; } /* 強(qiáng)制分頁(yè) */ img { max-width: 100% !important; } /* 防止圖片溢出 */ } “““ await page.add_style_tag(contentprint_style)這個(gè)技巧極其有用你可以通過(guò)它隱藏導(dǎo)航欄、廣告、側(cè)邊欄調(diào)整字體大小以及最重要的——控制分頁(yè)。3.2 征服分頁(yè)如何讓內(nèi)容在正確的位置斷開(kāi)HTML 內(nèi)容流轉(zhuǎn)換成多頁(yè) PDF分頁(yè)位置是不可預(yù)測(cè)的災(zāi)難區(qū)。文字在中間被切斷、表格跨頁(yè)顯示、標(biāo)題和內(nèi)容分離是家常便飯。使用 CSS 控制分頁(yè)CSS 提供了page-break-before,page-break-after,page-break-inside屬性現(xiàn)代標(biāo)準(zhǔn)中使用break-before,break-after,break-inside。這是控制分頁(yè)最核心的手段。page-break-before: always;確保該元素之前強(qiáng)制分頁(yè)。常用于新章節(jié)的標(biāo)題。page-break-after: avoid;盡量避免在該元素之后分頁(yè)。可以用于保持小段文字或標(biāo)題與下一段的連接。page-break-inside: avoid;非常重要盡量避免在該元素內(nèi)部斷頁(yè)。必須應(yīng)用于所有表格 (table)、代碼塊、圖片等不希望被分割的元素上。在你的打印樣式表中應(yīng)該至少包含media print { h1, h2 { page-break-after: avoid; } table, img, pre { page-break-inside: avoid; } .chapter { page-break-before: always; } }動(dòng)態(tài)計(jì)算與插入分頁(yè)符對(duì)于無(wú)法通過(guò)靜態(tài) CSS 解決的情況比如需要確保每個(gè)部分高度大致均勻你可以用 Playwright 執(zhí)行 JavaScript 來(lái)動(dòng)態(tài)計(jì)算并插入分頁(yè)元素async def smart_page_break(page): # 獲取所有需要獨(dú)立成塊的元素比如每個(gè)報(bào)告章節(jié)的容器 sections await page.query_selector_all(‘.report-section‘) for section in sections: # 這里可以計(jì)算section的位置和高度判斷是否接近頁(yè)面底部 # 如果太接近就在它前面插入一個(gè) div style“page-break-before: always;“/div # 這是一個(gè)簡(jiǎn)化示例實(shí)際邏輯更復(fù)雜 pass # 最后再生成PDF3.3 實(shí)現(xiàn)專(zhuān)業(yè)的頁(yè)眉、頁(yè)腳與頁(yè)碼display_header_footerTrue只是打開(kāi)了開(kāi)關(guān)。頁(yè)眉頁(yè)腳區(qū)域是一個(gè)獨(dú)立的、覆蓋在每頁(yè)內(nèi)容之上的層。你需要通過(guò)header_template和footer_template來(lái)定義它的內(nèi)容和樣式。模板中的特殊類(lèi)Playwright 在渲染頁(yè)眉頁(yè)腳時(shí)會(huì)識(shí)別幾個(gè)特殊的 CSS 類(lèi)并自動(dòng)替換其內(nèi)容.date格式化后的當(dāng)前日期。.title當(dāng)前頁(yè)面的標(biāo)題document.title。.url當(dāng)前頁(yè)面的 URL。.pageNumber當(dāng)前頁(yè)碼。.totalPages總頁(yè)數(shù)。定義模板的注意事項(xiàng)尺寸限制頁(yè)眉頁(yè)腳區(qū)域高度有限默認(rèn)大約 1-2cm。模板內(nèi)的 HTML 結(jié)構(gòu)必須非常簡(jiǎn)潔溢出部分會(huì)被裁剪。樣式內(nèi)聯(lián)模板中的樣式最好全部?jī)?nèi)聯(lián)因?yàn)橥獠繕邮奖砜赡軣o(wú)法應(yīng)用到這些區(qū)域。字體問(wèn)題默認(rèn)字體可能不支持中文。務(wù)必在模板中指定一個(gè)安全的字體族并確保該字體在系統(tǒng)或嵌入的 PDF 中可用。通常使用font-family: sans-serif;或具體的中文字體名。內(nèi)容對(duì)齊利用 Flexbox 或text-align來(lái)控制頁(yè)碼、標(biāo)題等元素的位置。一個(gè)實(shí)用的中文頁(yè)腳模板示例footer_template “““ div style“font-size: 10px; font-family: ‘SimSun‘, ‘Microsoft YaHei‘, sans-serif; width: 100%; padding: 0 20px; box-sizing: border-box; display: flex; justify-content: space-between;“ span機(jī)密文件/span span第 span class“pageNumber“/span 頁(yè)共 span class“totalPages“/span 頁(yè)/span span生成日期span class“date“/span/span /div “““注意.pageNumber和.totalPages的替換發(fā)生在 PDF 渲染的最后階段。這意味著你在模板中無(wú)法用 JavaScript 獲取或操作它們。所有樣式和布局必須在模板 HTML 中預(yù)先定義好。4. 從單次轉(zhuǎn)換到批量生產(chǎn)構(gòu)建健壯的轉(zhuǎn)換流水線一次成功的轉(zhuǎn)換令人欣喜但我們需要的是成百上千次穩(wěn)定、高效的轉(zhuǎn)換。這就需要構(gòu)建一個(gè)腳本處理各種邊界情況和異常。4.1 錯(cuò)誤處理與重試機(jī)制網(wǎng)絡(luò)不穩(wěn)定、目標(biāo)網(wǎng)站反爬、資源加載超時(shí)都會(huì)導(dǎo)致轉(zhuǎn)換失敗。你的腳本必須能優(yōu)雅地處理這些情況。import asyncio from playwright.async_api import Error as PlaywrightError async def convert_url_to_pdf(url, output_path, retries3): for attempt in range(retries): try: async with async_playwright() as p: browser await p.chromium.launch() context await browser.new_context( viewport{‘width‘: 1920, ‘height‘: 1080}, # 固定視口保證一致性 user_agent‘Mozilla/5.0 ...‘ # 可自定義UA ) page await context.new_page() # 設(shè)置超時(shí) page.set_default_timeout(60000) # 60秒超時(shí) await page.goto(url, wait_until‘networkidle‘) # ... 可能的滾動(dòng)、等待、樣式注入操作 ... await page.pdf(pathoutput_path, format‘A4‘, print_backgroundTrue) await browser.close() print(f“成功生成: {output_path}“) return True except PlaywrightError as e: print(f“第 {attempt 1} 次嘗試失敗URL: {url}, 錯(cuò)誤: {e}“) if attempt retries - 1: print(f“重試{retries}次后仍失敗跳過(guò): {url}“) return False await asyncio.sleep(2 ** attempt) # 指數(shù)退避等待 except Exception as e: print(f“發(fā)生未知錯(cuò)誤: {e}“) return False return False4.2 性能優(yōu)化與資源管理批量轉(zhuǎn)換時(shí)反復(fù)啟動(dòng)和關(guān)閉瀏覽器開(kāi)銷(xiāo)巨大。正確的做法是復(fù)用瀏覽器實(shí)例和上下文Context。async def batch_convert(url_list): async with async_playwright() as p: # 啟動(dòng)一個(gè)瀏覽器實(shí)例供所有任務(wù)復(fù)用 browser await p.chromium.launch() tasks [] for i, url in enumerate(url_list): # 為每個(gè)任務(wù)創(chuàng)建一個(gè)獨(dú)立的上下文隔離 cookies、localStorage 等 context await browser.new_context() task asyncio.create_task( convert_single_page(context, url, f‘output_{i}.pdf‘) ) tasks.append(task) # 并發(fā)執(zhí)行所有任務(wù) await asyncio.gather(*tasks, return_exceptionsTrue) await browser.close() async def convert_single_page(context, url, output_path): page await context.new_page() try: await page.goto(url) await page.pdf(pathoutput_path) finally: await page.close() # 關(guān)閉頁(yè)面釋放資源使用asyncio進(jìn)行并發(fā)控制可以極大提升批量轉(zhuǎn)換的速度。但要注意并發(fā)數(shù)并非越高越好需要根據(jù)機(jī)器性能內(nèi)存、CPU和目標(biāo)網(wǎng)站的承受能力進(jìn)行調(diào)整避免被封 IP 或拖垮本地機(jī)器。4.3 處理認(rèn)證與復(fù)雜交互有些網(wǎng)頁(yè)需要登錄或者需要點(diǎn)擊按鈕展開(kāi)內(nèi)容后才能完整打印。處理登錄await page.goto(‘login_page_url‘) await page.fill(‘#username‘, ‘your_username‘) await page.fill(‘#password‘, ‘your_password‘) await page.click(‘#submit-button‘) # 等待登錄成功跳轉(zhuǎn)到目標(biāo)頁(yè) await page.wait_for_navigation() # 保存登錄狀態(tài)cookies以便后續(xù)頁(yè)面使用 storage_state await context.storage_state() # 可以將 storage_state 保存為文件下次直接加載避免重復(fù)登錄執(zhí)行交互操作# 例如需要點(diǎn)擊“顯示全部”按鈕 await page.click(‘button.show-more‘) await page.wait_for_selector(‘.hidden-content‘, state‘visible‘) # 或者需要在一個(gè)下拉框中選擇選項(xiàng) await page.select_option(‘#report-format‘, ‘pdf‘) await page.wait_for_timeout(1000) # 等待頁(yè)面響應(yīng)5. 進(jìn)階場(chǎng)景與深度定制當(dāng)你掌握了基礎(chǔ)操作后可能會(huì)遇到更特殊的需求。5.1 生成“網(wǎng)頁(yè)快照”式PDF vs 生成“打印優(yōu)化”式PDF這是兩種不同的思路網(wǎng)頁(yè)快照目標(biāo)是盡可能原樣保留網(wǎng)頁(yè)在屏幕上的視覺(jué)效果包括固定的頭部、側(cè)邊欄、懸浮按鈕等。這時(shí)你可能需要設(shè)置一個(gè)非常大的頁(yè)面尺寸如viewport{‘width‘: 1440, ‘height‘: 9000}來(lái)避免內(nèi)容被截?cái)嗳缓笊梢粋€(gè)長(zhǎng)圖式的 PDF。page.pdf()的scale參數(shù)可以用來(lái)調(diào)整清晰度。打印優(yōu)化目標(biāo)是生成一份適合閱讀、打印的正式文檔。這就需要像前面章節(jié)所述大量使用打印CSS (media print) 來(lái)移除無(wú)關(guān)元素、調(diào)整字體、控制分頁(yè)。這更像是“內(nèi)容提取與重排”。根據(jù)你的需求選擇正確的路徑。對(duì)于內(nèi)部報(bào)告存檔前者可能更合適對(duì)于對(duì)外分發(fā)的正式文件后者是必須的。5.2 自定義紙張尺寸與方向除了預(yù)設(shè)的format你可以通過(guò)width和height參數(shù)直接指定自定義尺寸單位支持px,in,cm,mm。# 生成一個(gè)橫向的A4 PDF await page.pdf( path‘landscape.pdf‘, width‘297mm‘, height‘210mm‘, # A4 橫向的尺寸 print_backgroundTrue )5.3 與報(bào)告生成框架集成Playwright 非常適合作為后端服務(wù)與 Jinja2、React 等服務(wù)端渲染模板結(jié)合。工作流可以是后端用數(shù)據(jù)填充 HTML 模板Jinja2生成一個(gè)完整的 HTML 字符串。將這個(gè) HTML 字符串通過(guò)page.set_content(html_string)直接設(shè)置到 Playwright 的頁(yè)面中而不是導(dǎo)航到一個(gè)外部 URL。然后調(diào)用page.pdf()生成 PDF。from jinja2 import Template import asyncio html_template “““ !DOCTYPE html html headstyle/* 你的樣式 *//style/head bodyh1{{ title }}/h1p{{ content }}/p/body /html “““ template Template(html_template) rendered_html template.render(title“我的報(bào)告“, content“這是報(bào)告內(nèi)容...“) async def generate_pdf_from_html(html_string, output_path): async with async_playwright() as p: browser await p.chromium.launch() page await browser.new_page() # 關(guān)鍵直接將渲染好的HTML內(nèi)容設(shè)置到頁(yè)面 await page.set_content(html_string) # 等待頁(yè)面內(nèi)可能的圖片等資源加載如果是相對(duì)路徑 await page.wait_for_load_state(‘networkidle‘) await page.pdf(pathoutput_path) await browser.close()這種方法完全避免了網(wǎng)絡(luò)請(qǐng)求速度最快也最穩(wěn)定是生成動(dòng)態(tài)數(shù)據(jù)報(bào)告的首選方案。5.4 水印、加密與元數(shù)據(jù)Playwright 原生不直接支持添加水印或加密 PDF。但你可以通過(guò)變通方式實(shí)現(xiàn)水印在生成 PDF 前通過(guò)page.add_style_tag向頁(yè)面注入一個(gè)固定定位position: fixed、z-index很高的半透明水印層div。這個(gè)水印會(huì)出現(xiàn)在每一頁(yè)。加密與元數(shù)據(jù)Playwright 生成的 PDF 是“原始”的。如果需要加密或設(shè)置作者、主題等元數(shù)據(jù)可以借助其他 Python 庫(kù)如PyPDF2或pikepdf進(jìn)行后處理。# 后處理示例添加元數(shù)據(jù) import PyPDF2 def add_pdf_metadata(pdf_path, title, author): with open(pdf_path, ‘rb‘) as file: pdf_reader PyPDF2.PdfReader(file) pdf_writer PyPDF2.PdfWriter() for page_num in range(len(pdf_reader.pages)): pdf_writer.add_page(pdf_reader.pages[page_num]) # 添加元數(shù)據(jù) pdf_writer.add_metadata({ ‘/Title‘: title, ‘/Author‘: author, ‘/Creator‘: ‘Playwright PDF Generator‘, }) with open(pdf_path, ‘wb‘) as output_file: pdf_writer.write(output_file)6. 避坑指南那些我踩過(guò)的“坑”與解決方案最后分享幾個(gè)在實(shí)際項(xiàng)目中容易忽略卻可能導(dǎo)致失敗的“坑”。坑1字體缺失導(dǎo)致中文亂碼或布局異常問(wèn)題在服務(wù)器如 Ubuntu上生成的 PDF中文字體顯示為方框或亂碼或者因?yàn)樽煮w回退導(dǎo)致布局寬度計(jì)算錯(cuò)誤。 解決方案安裝中文字體在服務(wù)器上安裝字體包如fonts-wqy-microhei文泉驛微米黑或fonts-noto-cjk。sudo apt-get install fonts-wqy-microhei在 CSS 中顯式聲明字體在 HTML 的style或通過(guò) Playwright 注入的樣式中為body或特定元素指定已安裝的字體族。body { font-family: “WenQuanYi Micro Hei“, “Noto Sans CJK SC“, sans-serif; }使用page.add_font_face(實(shí)驗(yàn)性API)Playwright 允許你通過(guò) CSSfont-face規(guī)則嵌入字體文件需注意字體版權(quán)。坑2PDF 內(nèi)容被裁剪或縮放不當(dāng)問(wèn)題生成的 PDF 內(nèi)容顯示不全或者整體顯得特別小。 解決方案檢查viewport大小。如果頁(yè)面內(nèi)容很寬默認(rèn)的 viewport 可能不夠?qū)е虏季诌m配移動(dòng)端。在創(chuàng)建頁(yè)面時(shí)設(shè)置一個(gè)足夠大的視口await browser.new_page(viewport{‘width‘: 1920, ‘height‘: 1080})。檢查page.pdf()的scale參數(shù)。小于 1 會(huì)縮小大于 1 會(huì)放大。通常保持 1 即可除非有特殊縮放需求。檢查頁(yè)面 CSS 中是否有overflow: hidden之類(lèi)的屬性在打印媒體查詢中錯(cuò)誤地隱藏了內(nèi)容。坑3頁(yè)眉頁(yè)腳不顯示或樣式錯(cuò)亂問(wèn)題設(shè)置了display_header_footerTrue但什么都沒(méi)看到或者樣式很奇怪。 排查步驟確認(rèn)header_template或footer_template的 HTML 是有效的并且沒(méi)有因?yàn)楦叨冗^(guò)高被裁剪。給容器一個(gè)明確的高度和overflow: visible。檢查字體。頁(yè)眉頁(yè)腳區(qū)域默認(rèn)可能不繼承頁(yè)面字體務(wù)必在模板的內(nèi)聯(lián)樣式中指定font-family。檢查邊距margin。如果頁(yè)邊距設(shè)置得太大可能會(huì)擠壓掉頁(yè)眉頁(yè)腳的空間。適當(dāng)調(diào)整margin的top和bottom值。使用page.pdf()的debug模式如果存在或生成一個(gè)簡(jiǎn)單的模板先測(cè)試。坑4異步內(nèi)容加載不全問(wèn)題PDF 里缺少圖表或列表數(shù)據(jù)。 解決方案不要只依賴wait_until‘networkidle‘。結(jié)合使用page.wait_for_selector()或page.wait_for_function()來(lái)等待特定內(nèi)容渲染完成。對(duì)于基于前端框架如 React, Vue的應(yīng)用等待某個(gè)狀態(tài)標(biāo)志可能是更可靠的選擇。坑5在 Docker 或 CI/CD 環(huán)境中運(yùn)行失敗問(wèn)題本地運(yùn)行正常但在 Docker 容器中報(bào)錯(cuò)通常是關(guān)于瀏覽器無(wú)法啟動(dòng)。 解決方案使用 Playwright 官方提供的 Docker 鏡像它包含了所有必要的依賴。如果自己構(gòu)建鏡像務(wù)必按照官方文檔安裝所有系統(tǒng)依賴。一個(gè)典型的 Dockerfile 片段如下FROM mcr.microsoft.com/playwright/python:v1.40.0-noble RUN pip install playwright RUN playwright install chromium # 復(fù)制你的腳本并運(yùn)行“一行命令把 HTML 轉(zhuǎn) PDF” 是一個(gè)美好的起點(diǎn)它展示了 Playwright 的強(qiáng)大與便捷。但將其用于嚴(yán)肅的生產(chǎn)環(huán)境需要我們深入理解其原理并妥善處理樣式、布局、異步、性能等一系列工程化問(wèn)題。從簡(jiǎn)單的腳本到健壯的流水線這個(gè)過(guò)程本身也是對(duì)前端渲染、瀏覽器行為以及文檔排版理解的一次深化。希望這些從實(shí)戰(zhàn)中總結(jié)的經(jīng)驗(yàn)?zāi)軒湍惚荛_(kāi)我踩過(guò)的那些坑真正高效、可靠地駕馭這個(gè)強(qiáng)大的工具。