簡介pywebcopy 是一個(gè)用 Python 編寫的網(wǎng)頁抓取與歸檔庫面向需要保存完整網(wǎng)頁或整站鏡像的開發(fā)者、爬蟲學(xué)習(xí)者和資料歸檔人員解決頁面樣式、腳本、圖片等靜態(tài)資產(chǎn)分散、離線閱讀不便的問題。壓縮包共 32 個(gè)文件約 65KB以 19 個(gè) py 源碼模塊為核心輔以 8 個(gè) md 說明文檔、2 個(gè) yml 配置文件及 requirements、許可證等輔助文件便于閱讀實(shí)現(xiàn)、運(yùn)行示例和二次開發(fā)。已有 570 人學(xué)習(xí)或下載。它支持一次調(diào)用保存包含 CSS、JS 和圖像的網(wǎng)頁也可克隆完整網(wǎng)站并重新映射資產(chǎn)與鏈接代碼中涵蓋爬蟲、解析、API、頁面結(jié)構(gòu)與配置等模塊并強(qiáng)調(diào)遵循 robots.txt提供直接 API 與子類擴(kuò)展方式。對(duì)鏡像過程中的資源下載、鏈接重寫和配置管理有較清晰的組織適合用來理解站點(diǎn)鏡像流程、搭建離線歸檔腳本或進(jìn)行定制化抓取實(shí)踐。1. 一個(gè)離線歸檔需求把 pywebcopy 推到了臺(tái)前上周有位做前端的朋友找我一套已經(jīng)下線的活動(dòng)頁要原樣搬到內(nèi)網(wǎng)讓審核同事在沒網(wǎng)的環(huán)境里點(diǎn)開就能看。瀏覽器右鍵「另存為」最省事但一個(gè)頁面三十多張圖存下來的 HTML 里引用全被改成了本地絕對(duì)路徑換個(gè)目錄就裂碰上帶查詢串的 CDN 圖片文件名還會(huì)互相覆蓋最后只剩一張。這類活兒的正解是寫幾行 Python而 pywebcopy 就是專門干這個(gè)的庫——它把鏡像網(wǎng)頁和網(wǎng)站拆成「抓 HTML、找依賴、下載資源、改寫引用」四步最后落盤成一個(gè)雙擊就能打開的目錄。它適合做內(nèi)容歸檔、離線演示、設(shè)計(jì)參考站快照的從業(yè)者不適合直接拿來對(duì)付需要登錄態(tài)或者純 JS 渲染的站點(diǎn)這條邊界后面會(huì)反復(fù)提到。2. 最小閉環(huán)從 pip 到一份能雙擊打開的離線頁面先把單頁跑通再談?wù)尽：芏嗳松蟻砭蛃ave_website一個(gè)域名結(jié)果跑了兩小時(shí)抓回來一堆日歷頁和搜索結(jié)果頁磁盤漲了十幾個(gè) G真正想要的正文目錄反而沒抓全。單頁驗(yàn)證能讓你在十分鐘內(nèi)看清產(chǎn)物結(jié)構(gòu)知道資源落在哪、引用被改成什么樣后面出問題才有對(duì)照。2.1 它憑什么能把頁面拆開再裝回去pywebcopy 的內(nèi)部流程大致分三層。第一層是請(qǐng)求層用一個(gè)會(huì)話對(duì)象去拿 HTML帶上常規(guī)的 User-Agent 和超時(shí)第二層是解析層把 HTML 丟給解析器遍歷link[relstylesheet]、script[src]、img[src]、source[srcset]這些節(jié)點(diǎn)把所有外部引用收集成一張資源清單CSS 文件還會(huì)再進(jìn)去掃一遍url(...)和import第三層是改寫層資源逐個(gè)下載到本地同時(shí)把 HTML 里的絕對(duì) URL 替換成相對(duì)路徑。理解這個(gè)三層結(jié)構(gòu)很關(guān)鍵因?yàn)樗鼪Q定了失敗長什么樣。如果是請(qǐng)求層掛了你會(huì)看到ConnectionError或者 403如果是解析層漏了表現(xiàn)是「頁面能打開但某類資源沒有」比如字體文件全丟如果是改寫層出錯(cuò)表現(xiàn)是文件明明下載下來了但 HTML 里指向的還是外網(wǎng)地址離線打開一片空白。排查時(shí)先定位在哪一層比盲目加參數(shù)有用得多。還有一個(gè)容易忽略的點(diǎn)它改寫的是「引用」不是「內(nèi)容」。CSS 文件里如果嵌套了三層import或者 JS 里動(dòng)態(tài)拼了一個(gè)圖片路徑這些都不在靜態(tài)解析的射程內(nèi)。這不是缺陷是靜態(tài)抓取的天然邊界后面第 4 章會(huì)給出補(bǔ)刀方案。2.2 裝好環(huán)境跑通第一次 save_webpage建議單獨(dú)開一個(gè)虛擬環(huán)境因?yàn)?pywebcopy 會(huì)拉進(jìn) requests、beautifulsoup4、lxml 這一串依賴混在系統(tǒng)環(huán)境里容易和別的項(xiàng)目打架。python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate pip install pywebcopy python -c import pywebcopy; print(pywebcopy.__file__)最后一行能打印出安裝路徑說明導(dǎo)入沒問題。接下來是最小調(diào)用把目標(biāo)地址、產(chǎn)物根目錄、任務(wù)名三個(gè)東西給齊就行from pywebcopy import save_webpage # 單頁歸檔抓目標(biāo)頁本身和它引用的 css / js / 圖片 save_webpage( urlhttps://demo-site.test/blog/2024/activity.html, project_folder./mirror, # 產(chǎn)物根目錄不存在會(huì)自動(dòng)創(chuàng)建 project_nameactivity_2024, # 本次任務(wù)的子目錄名相當(dāng)于任務(wù) ID overwriteTrue, # 同名任務(wù)目錄已存在時(shí)整個(gè)覆蓋 delay0.3, # 每次請(qǐng)求之間的間隔單位秒 )這段代碼里url必須帶完整 scheme只寫域名會(huì)直接拋異常project_folder和project_name拼起來才是最終落在磁盤上的任務(wù)目錄所以project_name別隨便起建議用「日期 頁面 slug」方便日后回溯overwriteTrue在調(diào)試期很省心但它會(huì)刪掉整個(gè)舊目錄重來一旦你把它設(shè)成某個(gè)已經(jīng)歸檔好的歷史任務(wù)名之前的產(chǎn)物就沒了。歸檔場景下我一般設(shè)成False看到目錄已存在的報(bào)錯(cuò)反而說明沒誤傷。跑完之后先別急著驗(yàn)收用tree看一眼結(jié)構(gòu)比任何文檔都直觀tree -L 3 ./mirror/activity_2024 | head -402.3 產(chǎn)物目錄里到底落了什么不同版本在子目錄命名上會(huì)有些差異但骨架是一致的HTML 按 URL 的 path 映射成目錄層級(jí)資源集中落在頁面同級(jí)或子級(jí)的資源目錄里。第一次跑完建議對(duì)照下面這張表逐個(gè)確認(rèn)缺哪一類就說明哪一層的解析漏了。路徑 / 文件內(nèi)容驗(yàn)收要點(diǎn)project_folder/project_name/任務(wù)根目錄每次調(diào)用生成一個(gè)命名要可回溯與 URL path 對(duì)應(yīng)的.html頁面主體打開后正文應(yīng)完整不依賴網(wǎng)絡(luò)資源子目錄css / js / 字體 / 圖片目錄名隨版本略有差異以實(shí)際產(chǎn)物為準(zhǔn)HTML 內(nèi)的引用屬性已改寫成相對(duì)路徑用編輯器搜索https://應(yīng)基本清空原始 HTML 備份部分版本改寫前的副本有的話留著出問題能對(duì)比驗(yàn)收動(dòng)作可以很簡單把網(wǎng)線拔了雙擊那個(gè) HTML看三件事——正文在不在、樣式對(duì)不對(duì)、圖片裂沒裂。三樣都過單頁這條鏈路就算通了。有一樣不過回到 2.1 的三層模型去定位。2.4 三個(gè)必須先定下來的參數(shù)單頁場景真正需要調(diào)的參數(shù)不多但下面這幾個(gè)一旦定錯(cuò)后面整站鏡像會(huì)放大成災(zāi)難。參數(shù)默認(rèn)值作用我一般怎么定project_folder當(dāng)前目錄產(chǎn)物根目錄掛到獨(dú)立數(shù)據(jù)盤別放代碼倉庫里project_name按 URL 生成本次任務(wù)子目錄日期_slug歸檔場景絕不復(fù)用overwriteFalse同名任務(wù)是否覆蓋調(diào)試True正式歸檔Falsedelay0請(qǐng)求間隔秒目標(biāo)站有頻控就調(diào)到 0.51.0threadedFalse是否多線程下載單頁無所謂整站建議關(guān)zip_projectFalse抓完是否打包成 zip需要交付單個(gè)文件時(shí)開delay這個(gè)參數(shù)值得單獨(dú)說一句。它控制的是每次請(qǐng)求之間的等待看起來不起眼但在整站鏡像里是決定你會(huì)不會(huì)被目標(biāo)站限流的關(guān)鍵。很多人第一次跑整站就把delay設(shè)成 0、threaded開成 True結(jié)果前兩百個(gè)請(qǐng)求很順第三百個(gè)開始全變 429后面抓回來的全是錯(cuò)誤頁還得清空重來。3. 整站鏡像max_depth 與域名邊界決定你抓到的是站點(diǎn)還是垃圾場單頁跑通之后save_website的誘惑很大——一行調(diào)用抓一整個(gè)站。但整站鏡像的本質(zhì)是「從一個(gè)入口出發(fā)做廣度優(yōu)先遍歷」你不畫邊界它就會(huì)順著分頁、日歷、標(biāo)簽、搜索參數(shù)一路爬下去最后抓回來的東西和你想歸檔的內(nèi)容可能只重合三成。這一章講的就是怎么畫這個(gè)邊界。3.1 save_website 和 save_webpage 的差別不在抓多抓少兩者真正的差別在于「有沒有 URL 隊(duì)列」。save_webpage是一次性的解析當(dāng)前頁、下載依賴、改寫、結(jié)束不關(guān)心頁面里指向的其他 HTML。save_website維護(hù)一個(gè)待抓隊(duì)列每抓到一個(gè) HTML 就從中提取站內(nèi)鏈接判斷是否在白名單內(nèi)、是否超過深度、是否命中黑名單通過了才入隊(duì)。這個(gè)機(jī)制帶來兩個(gè)直接后果。第一深度是相對(duì)入口頁計(jì)算的入口頁算第 0 層它鏈出去的算第 1 層max_depth3意味著最多跟三層再深的頁面不會(huì)被抓。第二去重完全依賴 URL 字符串同一個(gè)頁面如果有?fromhome和?fromlist兩個(gè)入口會(huì)被當(dāng)成兩個(gè)不同頁面各抓一遍產(chǎn)物里出現(xiàn)兩份內(nèi)容相同、路徑不同的 HTML。這一點(diǎn)在 CMS 站點(diǎn)上特別常見。所以整站鏡像的第一件事不是調(diào)深度而是想清楚「哪些 URL 形態(tài)是同一個(gè)頁面的不同馬甲」把它們?nèi)M(jìn)黑名單。3.2 用 allowed_domains 和 blacklist_urls 畫一個(gè)抓取圍欄下面這份調(diào)用是我在歸檔一個(gè)內(nèi)容站時(shí)的常用配置注釋寫得比較細(xì)可以直接照著改from pywebcopy import save_website save_website( urlhttps://demo-site.test/, project_folder./mirror, project_namedemo_site_full, # 從入口算起最多跟三層再深基本是分頁和日歷價(jià)值低且量大 max_depth3, # 域名白名單寫域名不寫 URL子域要單獨(dú)列出來 allowed_domains[demo-site.test, static.demo-site.test], # 正則黑名單注意把點(diǎn)號(hào)轉(zhuǎn)義否則 . 會(huì)匹配任意字符 blacklist_urls[ rdemo-site\.test/logout, rdemo-site\.test/search\?, rdemo-site\.test/calendar/, rdemo-site\.test/tag/, r\.(zip|pdf|mp4|iso)$, # 大文件先排除避免把磁盤打滿 ], delay1.0, # 一秒一個(gè)請(qǐng)求禮貌且不容易被限流 threadedFalse, # 大站關(guān)掉多線程隊(duì)列順序更可控 overwriteFalse, )allowed_domains是一個(gè)常見翻車點(diǎn)。它的語義是「允許抓取的域名」不包含主域之外的 CDN 域名時(shí)頁面里那些托管在 CDN 上的圖片可能抓不到。穩(wěn)妥做法是先把頁面里的資源域名掃一遍把靜態(tài)資源域也加進(jìn)去。至于資源抓取是否嚴(yán)格受這個(gè)白名單約束不同版本行為有差異所以最終還是要靠產(chǎn)物驗(yàn)收來判斷別把它當(dāng)成鐵律。blacklist_urls用的是正則匹配匹配對(duì)象是完整 URL。寫的時(shí)候把/logout、/search?、/calendar/這幾類先排掉能省掉一大半無效請(qǐng)求。帶查詢串的 URL 記得把?也轉(zhuǎn)義進(jìn)去否則只匹配到路徑部分。3.3 delay 和 threaded 的取舍限速比并發(fā)重要整站鏡像最常見的誤區(qū)是把「抓得快」當(dāng)成目標(biāo)。實(shí)際上你真正要的是「抓得全且不重來」而重來的成本遠(yuǎn)高于慢一點(diǎn)的成本。配置組合適用場景風(fēng)險(xiǎn)threadedFalse, delay0.5~1.0絕大多數(shù)整站歸檔慢但產(chǎn)物完整、可復(fù)現(xiàn)threadedFalse, delay0本地起服務(wù)測試對(duì)真實(shí)站點(diǎn)不要這么干threadedTrue, delay1.0大型靜態(tài)站、內(nèi)網(wǎng)環(huán)境隊(duì)列順序亂日志難對(duì)賬threadedTrue, delay0不推薦極易觸發(fā)限流抓到大量錯(cuò)誤頁我自己的習(xí)慣是第一次跑永遠(yuǎn)用單線程加 1 秒間隔先抓個(gè)二三十頁看看產(chǎn)物質(zhì)量和日志確認(rèn)沒問題再?zèng)Q定要不要提速。提速的方式我傾向于「分批跑」而不是「調(diào)高并發(fā)」——把站點(diǎn)按欄目拆成多個(gè)任務(wù)每個(gè)任務(wù)用不同的project_name跑完再合并。這樣任何一個(gè)批次失敗損失都是局部可重跑的。還有一點(diǎn)容易被忽略delay作用的是請(qǐng)求之間的間隔但整站鏡像里有一部分耗時(shí)是資源下載那部分如果不走同一個(gè)限速器實(shí)際壓力可能比你預(yù)期的大。所以跑的時(shí)候盯著目標(biāo)站的響應(yīng)碼看一旦出現(xiàn) 429 或 503 的批量出現(xiàn)立刻停把delay翻倍再繼續(xù)。3.4 robots 與 bypass_robots 的邊界pywebcopy 有一個(gè)bypass_robots參數(shù)含義是抓取時(shí)是否忽略目標(biāo)站的 robots.txt 限制。這個(gè)參數(shù)的默認(rèn)值是False也就是默認(rèn)遵守。我的建議很明確除了你自己擁有或者明確獲得授權(quán)的站點(diǎn)其他場景一律保持默認(rèn)。robots.txt 表達(dá)的是站點(diǎn)運(yùn)營方對(duì)爬蟲的意愿繞過它既可能違反站點(diǎn)條款也會(huì)讓你在對(duì)方日志里變成明顯的異常流量。歸檔公開內(nèi)容時(shí)正確的做法是先看一眼目標(biāo)站的 robots.txt瀏覽器直接訪問/robots.txt就能看確認(rèn)你要抓的路徑不在禁止列表里再按delay限速慢跑。還有一層現(xiàn)實(shí)考慮即便技術(shù)上繞過了對(duì)方一旦識(shí)別出高頻訪問封的是 IP 段你的整個(gè)抓取任務(wù)會(huì)從某一刻起全部返回 403而你已經(jīng)抓下來的半成品還得手工清理。這筆賬怎么算都不劃算。4. 避坑與排查五條用真實(shí)故障換來的記錄這一章里的每一條都是我在不同項(xiàng)目里實(shí)實(shí)在在撞過的。按「現(xiàn)象 → 原因 → 解決」寫方便你對(duì)照自己的報(bào)錯(cuò)直接定位。4.1 頁面能打開但樣式全丟、圖片全裂現(xiàn)象HTML 雙擊能打開正文文字也在但整頁沒有排版控制臺(tái)里一堆 404指向的路徑形如./_internal/xxx/default.css實(shí)際磁盤上沒有這個(gè)文件。原因CSS 文件內(nèi)部的url(...)引用是相對(duì)于 CSS 文件自身位置的不是相對(duì)于 HTML。pywebcopy 在改寫 CSS 內(nèi)容時(shí)如果import形成了多層嵌套或者 CSS 里用了url(../fonts/a.woff2)這種跨級(jí)相對(duì)路徑改寫結(jié)果可能算錯(cuò)基準(zhǔn)目錄導(dǎo)致資源被下載到了另一個(gè)位置而引用路徑指向空處。解決先手工確認(rèn)基準(zhǔn)。打開產(chǎn)物里的 CSS 文件搜索url(看改寫后的路徑再對(duì)照磁盤上資源實(shí)際所在目錄兩者一比對(duì)就知道偏移在哪。如果只是少量文件對(duì)不上寫個(gè)腳本按「CSS 文件所在目錄 引用路徑」把文件挪到正確位置或者反向改寫 CSS 里的路徑import re from pathlib import Path def fix_css_urls(css_file: Path, assets_dir: Path): 把 CSS 里指向不存在文件的 url() 改成指向 assets_dir 下的同名文件 text css_file.read_text(encodingutf-8, errorsignore) def repl(m): ref m.group(1).strip(\) if ref.startswith((data:, http://, https://)): return m.group(0) name Path(ref).name candidate assets_dir / name if candidate.exists(): rel candidate.relative_to(css_file.parent) return furl({rel.as_posix()}) return m.group(0) css_file.write_text(re.sub(rurl\(([^)])\), repl, text), encodingutf-8)這段邏輯的關(guān)鍵是relative_to它算出的是從 CSS 文件所在目錄到資源文件的真實(shí)相對(duì)路徑比手工拼字符串可靠。參數(shù)assets_dir要指向你實(shí)際發(fā)現(xiàn)資源所在的目錄跑之前先find一遍確認(rèn)。4.2 抓回來一片空白HTML 里只有一個(gè)空的掛載點(diǎn)現(xiàn)象產(chǎn)物 HTML 打開是白屏查看源碼只有div idapp/div和幾個(gè) script 標(biāo)簽正文一個(gè)字都沒有。原因目標(biāo)是單頁應(yīng)用正文由 JS 在瀏覽器里渲染出來服務(wù)器返回的原始 HTML 本身就是空的。pywebcopy 拿到的是服務(wù)器響應(yīng)不是渲染后的 DOM所以它抓到的就是那個(gè)空殼。解決在 pywebcopy 之前插一步預(yù)渲染用無頭瀏覽器把頁面跑一遍、拿到渲染后的 HTML再喂給后續(xù)流程。常見做法是from playwright.sync_api import sync_playwright def render_html(url: str, timeout: int 30000) - str: 用無頭瀏覽器拿到 JS 執(zhí)行完之后的 DOM 快照 with sync_playwright() as p: browser p.chromium.launch(headlessTrue) page browser.new_page() # networkidle 表示等網(wǎng)絡(luò)靜默比 load 更適合異步渲染的頁面 page.goto(url, wait_untilnetworkidle, timeouttimeout) html page.content() browser.close() return html拿到html之后有兩條路一是寫入本地臨時(shí)文件起一個(gè)python -m http.server讓 pywebcopy 從這個(gè)本地地址抓這樣資源引用還能正常解析二是自己解析這份 HTML 把資源抓全完全繞開 pywebcopy 的抓取層。前者改動(dòng)小后者可控性強(qiáng)我一般先用前者快速驗(yàn)證。4.3 一批圖片落地后只剩一張文件名互相覆蓋現(xiàn)象頁面引用了logo.png?v1、logo.png?v2、logo.png?v3三個(gè)版本產(chǎn)物目錄里只有一張logo.png頁面上三個(gè)位置顯示的是同一張圖。原因落盤時(shí)文件名通常取自 URL 的 path 部分查詢串被丟掉了。三個(gè) URL 的 path 完全相同自然寫到同一個(gè)文件后寫的覆蓋先寫的。解決抓取前先自己把資源本地化用「path 查詢串哈?！股晌ㄒ晃募膶?HTML 里的引用為相對(duì)路徑然后再讓 pywebcopy 處理頁面。這樣 pywebcopy 看到的已經(jīng)是本地相對(duì)引用不會(huì)再重復(fù)下載也不會(huì)撞名import hashlib, os from urllib.parse import urljoin, urlsplit import requests from bs4 import BeautifulSoup ASSET_ATTRS {img: src, script: src, link: href} def localize_assets(page_url: str, html: str, out_dir: str ./assets) - str: os.makedirs(out_dir, exist_okTrue) soup BeautifulSoup(html, html.parser) for tag, attr in ASSET_ATTRS.items(): for node in soup.find_all(tag): raw node.get(attr) if not raw or raw.startswith(data:): continue abs_url urljoin(page_url, raw) parts urlsplit(abs_url) # 用查詢串的短哈希做文件名后綴保證同 path 不同 query 不撞 digest hashlib.md5(parts.query.encode()).hexdigest()[:8] if parts.query else base os.path.basename(parts.path) or index if digest: stem, dot, ext base.rpartition(.) base f{stem}.{digest}.{ext} if dot else f{base}.{digest} target os.path.join(out_dir, base) if not os.path.exists(target): resp requests.get(abs_url, timeout15) resp.raise_for_status() with open(target, wb) as f: f.write(resp.content) node[attr] os.path.relpath(target, .).replace(os.sep, /) return str(soup)digest只取 8 位沖突概率在單站規(guī)模下可以忽略os.path.relpath算出相對(duì)當(dāng)前工作目錄的路徑所以調(diào)用這個(gè)函數(shù)時(shí)的工作目錄要和后續(xù) pywebcopy 的project_folder保持同一基準(zhǔn)否則改寫出來的相對(duì)路徑會(huì)偏。4.4 中文全是亂碼英文正?，F(xiàn)象抓下來的頁面中文變成???–?這種字符英文和數(shù)字完全正常。原因目標(biāo)站響應(yīng)頭里沒給charset或者給了一個(gè)錯(cuò)誤的默認(rèn)值比如ISO-8859-1而頁面實(shí)際是 GBK 或 UTF-8 編碼。requests 在沒有明確聲明時(shí)會(huì)按 HTTP 規(guī)范回退到 ISO-8859-1解出來就是亂碼。解決抓之前先探一次編碼再?zèng)Q定怎么傳。探測代碼如下import requests resp requests.get(https://demo-site.test/news/legacy.html, timeout10) # 先看響應(yīng)頭聲明再看內(nèi)容推測兩者不一致時(shí)以推測為準(zhǔn) print(declared:, resp.encoding) print(detected:, resp.apparent_encoding)較新版本的 pywebcopy 支持傳入編碼相關(guān)的關(guān)鍵字參數(shù)把探測到的值傳進(jìn)去即可。如果你的版本不認(rèn)這個(gè)參數(shù)退路是先按正確編碼把內(nèi)容寫成臨時(shí) HTML 文件本地起一個(gè) http 服務(wù)讓 pywebcopy 從本地地址抓——本地服務(wù)的響應(yīng)頭你可以完全控制編碼問題就繞過去了。4.5 整站跑到一半卡住內(nèi)存持續(xù)上漲現(xiàn)象任務(wù)跑到幾百個(gè)頁面之后速度明顯變慢進(jìn)程內(nèi)存一路漲到幾個(gè) G最后要么被系統(tǒng)殺掉要么一直掛在那里不動(dòng)。原因遞歸隊(duì)列沒有做上限控制加上threadedTrue時(shí)多個(gè)線程同時(shí)往隊(duì)列里塞 URL去重表膨脹再加上每個(gè)頁面的 DOM 對(duì)象沒有被及時(shí)釋放累積起來就是內(nèi)存雪崩。站點(diǎn)越大、重復(fù)入口越多這個(gè)問題越明顯。解決三個(gè)動(dòng)作一起做。第一關(guān)掉多線程threadedFalse把并發(fā)壓力換成可預(yù)測的順序執(zhí)行。第二把blacklist_urls補(bǔ)齊尤其是帶分頁參數(shù)的?page、帶排序參數(shù)的?sort這些是隊(duì)列膨脹的主要來源。第三分批跑按欄目或按字母區(qū)間拆成多個(gè)任務(wù)每個(gè)任務(wù)用獨(dú)立的project_name跑完再合并目錄。批量跑的時(shí)候在外面套一層循環(huán)單任務(wù)失敗不影響后續(xù)日志里記清楚哪一批失敗了好補(bǔ)跑。注意整站鏡像前先估算體量。用max_depth1試跑一次看單頁平均產(chǎn)物大小和頁面數(shù)乘以預(yù)估總頁數(shù)得出來的數(shù)字如果超過磁盤剩余空間的七成就先拆批次。5. 封裝成能反復(fù)用的鏡像工具批處理、增量與產(chǎn)物校驗(yàn)單次調(diào)用解決不了「每周歸檔一次」這種需求。真正要長期用得往上包一層命令行入口負(fù)責(zé)批量調(diào)度狀態(tài)庫負(fù)責(zé)跳過沒變的頁面校驗(yàn)?zāi)_本負(fù)責(zé)在交付前兜底。這三塊加起來不到兩百行但能把返工率壓下去一大截。5.1 用 argparse 包一層命令行一次傳多個(gè)入口核心訴求是「一條命令跑完一批 URL單個(gè)失敗不中斷」。下面這版實(shí)現(xiàn)故意做得樸素沒有引入額外依賴import argparse import time from pathlib import Path from urllib.parse import urlsplit from pywebcopy import save_webpage, save_website def build_parser(): p argparse.ArgumentParser(description批量鏡像網(wǎng)頁或站點(diǎn)) p.add_argument(urls, nargs, help入口 URL可以傳多個(gè)) p.add_argument(-o, --out, default./mirror, help產(chǎn)物根目錄) p.add_argument(-n, --name, defaultNone, help任務(wù)名默認(rèn)按時(shí)間戳生成) p.add_argument(-d, --depth, typeint, default1, help1 表示只抓單頁大于 1 表示按深度遞歸) p.add_argument(--delay, typefloat, default0.8, help請(qǐng)求間隔秒) p.add_argument(--overwrite, actionstore_true) return p def main(): args build_parser().parse_args() stamp time.strftime(%Y%m%d_%H%M%S) for idx, url in enumerate(args.urls): name args.name or fjob_{stamp}_{idx} common dict( project_folderargs.out, project_namename, overwriteargs.overwrite, delayargs.delay, threadedFalse, ) try: if args.depth 1: save_webpage(urlurl, **common) else: # netloc 作為域名白名單生產(chǎn)環(huán)境建議顯式傳入配置 domain urlsplit(url).netloc save_website(urlurl, max_depthargs.depth, allowed_domains[domain], **common) print(f[ok] {url} - {Path(args.out) / name}) except Exception as exc: # 單個(gè)任務(wù)失敗只記錄不中斷整批 print(f[fail] {url}: {exc}) if __name__ __main__: main()幾個(gè)設(shè)計(jì)取舍值得說明。depth1走單頁分支、大于 1 走整站分支是為了讓同一個(gè)命令既能做快速快照又能做深度歸檔不用記兩套參數(shù)。urlsplit(url).netloc直接把入口域名當(dāng)白名單省掉手填但如果目標(biāo)站的資源在獨(dú)立 CDN 域上這個(gè)默認(rèn)值會(huì)漏抓所以正式場景還是建議加一個(gè)--allow-domain參數(shù)手動(dòng)補(bǔ)。異常捕獲用寬泛的Exception在批處理場景里是對(duì)的——你寧可吞掉一條錯(cuò)誤日志也不愿意因?yàn)榈?3 個(gè) URL 掛了導(dǎo)致后面 50 個(gè)沒跑。5.2 用 SQLite 記狀態(tài)跳過沒變化的頁面每周歸檔一次同樣的站點(diǎn)如果每次都全量重抓時(shí)間和帶寬都浪費(fèi)在沒變的頁面上。判斷頁面變沒變最可靠的是服務(wù)端給的ETag和Last-Modified這兩個(gè)頭在 HEAD 請(qǐng)求里就能拿到成本極低。先建一張狀態(tài)表主鍵是 URL記錄兩個(gè)校驗(yàn)值和時(shí)間戳import sqlite3 DB mirror_state.db def init_db(): conn sqlite3.connect(DB) conn.execute( CREATE TABLE IF NOT EXISTS pages ( url TEXT PRIMARY KEY, etag TEXT, last_modified TEXT, fetched_at INTEGER, status INTEGER ) ) conn.commit() return conn def need_refetch(conn, url, etagNone, last_modifiedNone): row conn.execute( SELECT etag, last_modified FROM pages WHERE url ?, (url,) ).fetchone() if row is None: return True # 沒記錄過必須抓 if etag and etag ! row[0]: return True # ETag 變了內(nèi)容有更新 if last_modified and last_modified ! row[1]: return True return Falseneed_refetch的判斷順序有講究先看有沒有記錄再看 ETag最后看 Last-Modified。ETag 優(yōu)先級(jí)更高是因?yàn)樗ǔＪ菍?duì)內(nèi)容做哈希算出來的比時(shí)間戳精確有些服務(wù)器只給其中一個(gè)所以兩個(gè)都要兼容。注意etag and ...這個(gè)寫法etag為空字符串時(shí)直接短路返回False避免把「服務(wù)端沒給 ETag」誤判成「內(nèi)容變了」而觸發(fā)全量重抓。配套的調(diào)度循環(huán)大致是先對(duì)每個(gè) URL 發(fā) HEAD 請(qǐng)求拿兩個(gè)頭查庫判斷要不要抓要抓才調(diào) pywebcopy抓完把新值寫回去。整站鏡像場景下這套邏輯要放在 URL 入隊(duì)的那一層而不是抓完再判斷否則省不下請(qǐng)求。5.3 交付前的三道校驗(yàn)別讓殘缺產(chǎn)物出門抓完之后最怕的是「看起來抓完了其實(shí)缺了一半」。寫一個(gè)校驗(yàn)函數(shù)把產(chǎn)物目錄里所有 HTML 的相對(duì)引用掃一遍檢查目標(biāo)文件是否存在import re from pathlib import Path from urllib.parse import unquote, urlsplit REF_RE re.compile(r(?:src|href)([^])) def find_missing_refs(root: str, limit: int 30): 掃描產(chǎn)物里所有本地引用返回指向不存在文件的條目 root_path Path(root) missing [] for html in root_path.rglob(*.html): text html.read_text(encodingutf-8, errorsignore) for ref in REF_RE.findall(text): if ref.startswith((http://, https://, data:, #, mailto:, javascript:)): continue # 去掉查詢串和錨點(diǎn)再解碼百分號(hào)編碼才是真實(shí)的文件路徑 target (html.parent / unquote(urlsplit(ref).path)).resolve() if not target.exists(): missing.append((str(html.relative_to(root_path)), ref)) if len(missing) limit: return missing return missing三個(gè)細(xì)節(jié)決定這個(gè)腳本準(zhǔn)不準(zhǔn)。第一過濾協(xié)議前綴時(shí)要帶上javascript:和mailto:否則一堆內(nèi)聯(lián)腳本會(huì)被誤報(bào)。第二必須unquote因?yàn)?HTML 里的中文路徑通常是百分號(hào)編碼的不還原就會(huì)算出不存在的路徑。第三用limit截?cái)嗾军c(diǎn)大的時(shí)候缺失項(xiàng)可能有幾千條全部打印出來反而看不到重點(diǎn)先看前三十條足夠判斷是系統(tǒng)性問題還是零星遺漏。校驗(yàn)結(jié)果怎么用如果缺失集中在某幾類資源上比如所有字體都缺說明是解析層的系統(tǒng)性問題回到第 4 章對(duì)應(yīng)條目排查如果缺失是零散的、每次跑的都不一樣多半是網(wǎng)絡(luò)超時(shí)導(dǎo)致的下載失敗把delay調(diào)大重跑一遍缺失的部分即可。6. 進(jìn)階把預(yù)渲染和特性補(bǔ)刀接進(jìn)同一條流水線走到這一步pywebcopy 能覆蓋的場景已經(jīng)比較清楚了靜態(tài)渲染的內(nèi)容站、文檔站、活動(dòng)頁歸檔幾行代碼就能出可用產(chǎn)物。剩下的短板集中在兩類一類是 JS 渲染一類是 HTML 特性覆蓋不全這兩塊都可以在調(diào)用它之前用幾十行代碼補(bǔ)上。先看一張對(duì)比表把不同頁面類型的推薦路徑列清楚省得每次都重新想頁面類型直接 save_webpage預(yù)渲染后再抓說明服務(wù)端渲染的內(nèi)容頁可用不必要首選方案成本最低靜態(tài)文檔 / 博客可用不必要注意 CSS 里的字體和 import單頁應(yīng)用產(chǎn)物為空殼必選先拿到渲染后 DOM 再抓重圖片的電商詳情頁部分可用建議srcset 多分辨率容易漏抓需要登錄的頁面不可用不可用會(huì)話態(tài)不在這個(gè)工具的射程內(nèi)預(yù)渲染那一步在第 4 章已經(jīng)給過代碼這里補(bǔ)一個(gè)把兩者串起來的做法先用無頭瀏覽器拿到渲染后的 HTML寫到一個(gè)臨時(shí)目錄起一個(gè)本地靜態(tài)服務(wù)再把本地地址交給 pywebcopy。這樣 pywebcopy 的解析和改寫能力仍然能用上同時(shí)它面對(duì)的不再是空殼。落地時(shí)注意本地服務(wù)的端口要固定別用隨機(jī)端口否則日志里的產(chǎn)物路徑每次都不一樣排查時(shí)對(duì)不上號(hào)。另一個(gè)高頻遺漏是srcset。響應(yīng)式圖片會(huì)給多個(gè)分辨率候選pywebcopy 對(duì)這類屬性的處理在不同版本上不一致穩(wěn)妥做法是在抓之前把srcset壓成一個(gè)src只保最大的一張import re def flatten_srcset(html: str) - str: 把 srcset 壓成單個(gè) src取候選列表里最后通常最大的一張 def repl(m): candidates [c.strip().split()[0] for c in m.group(1).split(,) if c.strip()] if not candidates: return m.group(0) return fsrc{candidates[-1]} return re.sub(rsrcset([^]), repl, html)這個(gè)替換是粗暴的它不管原來的img上有沒有src直接覆蓋。生產(chǎn)環(huán)境里要先判斷節(jié)點(diǎn)是否已有src有的話只在srcset存在時(shí)才改沒有的話補(bǔ)一個(gè)。取最后一張是因?yàn)榇蠖鄶?shù)站點(diǎn)的srcset按從小到大排列最后一張分辨率最高離線歸檔場景下清晰度比體積重要。最后說個(gè)我自己的習(xí)慣每次歸檔任務(wù)開始前先在紙上寫三行——這次要抓什么、抓到什么程度算完成、產(chǎn)物交給誰。這三行寫不出來說明需求還沒想清楚這時(shí)候調(diào)參數(shù)都是瞎調(diào)。鏡像網(wǎng)頁這件事工具只占三成剩下七成是想清楚邊界。前面那些踩坑記錄有一半是因?yàn)槲乙婚_始沒寫這三行。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取