簡介pywebcopy 是一個用 Python 編寫的網(wǎng)頁抓取與歸檔庫面向需要保存完整網(wǎng)頁或整站鏡像的開發(fā)者、爬蟲學(xué)習(xí)者和資料歸檔人員解決頁面樣式、腳本、圖片等靜態(tài)資產(chǎn)分散、離線閱讀不便的問題。壓縮包共 32 個文件約 65KB以 19 個 py 源碼模塊為核心輔以 8 個 md 說明文檔、2 個 yml 配置文件及 requirements、許可證等輔助文件便于閱讀實現(xià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ò)展方式。對鏡像過程中的資源下載、鏈接重寫和配置管理有較清晰的組織適合用來理解站點鏡像流程、搭建離線歸檔腳本或進(jìn)行定制化抓取實踐。1. 一個離線歸檔需求把 pywebcopy 推到了臺前上周有位做前端的朋友找我一套已經(jīng)下線的活動頁要原樣搬到內(nèi)網(wǎng)讓審核同事在沒網(wǎng)的環(huán)境里點開就能看。瀏覽器右鍵「另存為」最省事但一個頁面三十多張圖存下來的 HTML 里引用全被改成了本地絕對路徑換個目錄就裂碰上帶查詢串的 CDN 圖片文件名還會互相覆蓋最后只剩一張。這類活兒的正解是寫幾行 Python而 pywebcopy 就是專門干這個的庫——它把鏡像網(wǎng)頁和網(wǎng)站拆成「抓 HTML、找依賴、下載資源、改寫引用」四步最后落盤成一個雙擊就能打開的目錄。它適合做內(nèi)容歸檔、離線演示、設(shè)計參考站快照的從業(yè)者不適合直接拿來對付需要登錄態(tài)或者純 JS 渲染的站點這條邊界后面會反復(fù)提到。2. 最小閉環(huán)從 pip 到一份能雙擊打開的離線頁面先把單頁跑通再談?wù)?。很多人上來就save_website一個域名結(jié)果跑了兩小時抓回來一堆日歷頁和搜索結(jié)果頁磁盤漲了十幾個 G真正想要的正文目錄反而沒抓全。單頁驗證能讓你在十分鐘內(nèi)看清產(chǎn)物結(jié)構(gòu)知道資源落在哪、引用被改成什么樣后面出問題才有對照。2.1 它憑什么能把頁面拆開再裝回去pywebcopy 的內(nèi)部流程大致分三層。第一層是請求層用一個會話對象去拿 HTML帶上常規(guī)的 User-Agent 和超時第二層是解析層把 HTML 丟給解析器遍歷link[relstylesheet]、script[src]、img[src]、source[srcset]這些節(jié)點把所有外部引用收集成一張資源清單CSS 文件還會再進(jìn)去掃一遍url(...)和import第三層是改寫層資源逐個下載到本地同時把 HTML 里的絕對 URL 替換成相對路徑。理解這個三層結(jié)構(gòu)很關(guān)鍵因為它決定了失敗長什么樣。如果是請求層掛了你會看到ConnectionError或者 403如果是解析層漏了表現(xiàn)是「頁面能打開但某類資源沒有」比如字體文件全丟如果是改寫層出錯表現(xiàn)是文件明明下載下來了但 HTML 里指向的還是外網(wǎng)地址離線打開一片空白。排查時先定位在哪一層比盲目加參數(shù)有用得多。還有一個容易忽略的點它改寫的是「引用」不是「內(nèi)容」。CSS 文件里如果嵌套了三層import或者 JS 里動態(tài)拼了一個圖片路徑這些都不在靜態(tài)解析的射程內(nèi)。這不是缺陷是靜態(tài)抓取的天然邊界后面第 4 章會給出補(bǔ)刀方案。2.2 裝好環(huán)境跑通第一次 save_webpage建議單獨開一個虛擬環(huán)境因為 pywebcopy 會拉進(jìn) requests、beautifulsoup4、lxml 這一串依賴混在系統(tǒng)環(huán)境里容易和別的項目打架。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ù)名三個東西給齊就行from pywebcopy import save_webpage # 單頁歸檔抓目標(biāo)頁本身和它引用的 css / js / 圖片 save_webpage( urlhttps://demo-site.test/blog/2024/activity.html, project_folder./mirror, # 產(chǎn)物根目錄不存在會自動創(chuàng)建 project_nameactivity_2024, # 本次任務(wù)的子目錄名相當(dāng)于任務(wù) ID overwriteTrue, # 同名任務(wù)目錄已存在時整個覆蓋 delay0.3, # 每次請求之間的間隔單位秒 )這段代碼里url必須帶完整 scheme只寫域名會直接拋異常project_folder和project_name拼起來才是最終落在磁盤上的任務(wù)目錄所以project_name別隨便起建議用「日期 頁面 slug」方便日后回溯overwriteTrue在調(diào)試期很省心但它會刪掉整個舊目錄重來一旦你把它設(shè)成某個已經(jīng)歸檔好的歷史任務(wù)名之前的產(chǎn)物就沒了。歸檔場景下我一般設(shè)成False看到目錄已存在的報錯反而說明沒誤傷。跑完之后先別急著驗收用tree看一眼結(jié)構(gòu)比任何文檔都直觀tree -L 3 ./mirror/activity_2024 | head -402.3 產(chǎn)物目錄里到底落了什么不同版本在子目錄命名上會有些差異但骨架是一致的HTML 按 URL 的 path 映射成目錄層級資源集中落在頁面同級或子級的資源目錄里。第一次跑完建議對照下面這張表逐個確認(rèn)缺哪一類就說明哪一層的解析漏了。路徑 / 文件內(nèi)容驗收要點project_folder/project_name/任務(wù)根目錄每次調(diào)用生成一個命名要可回溯與 URL path 對應(yīng)的.html頁面主體打開后正文應(yīng)完整不依賴網(wǎng)絡(luò)資源子目錄css / js / 字體 / 圖片目錄名隨版本略有差異以實際產(chǎn)物為準(zhǔn)HTML 內(nèi)的引用屬性已改寫成相對路徑用編輯器搜索https://應(yīng)基本清空原始 HTML 備份部分版本改寫前的副本有的話留著出問題能對比驗收動作可以很簡單把網(wǎng)線拔了雙擊那個 HTML看三件事——正文在不在、樣式對不對、圖片裂沒裂。三樣都過單頁這條鏈路就算通了。有一樣不過回到 2.1 的三層模型去定位。2.4 三個必須先定下來的參數(shù)單頁場景真正需要調(diào)的參數(shù)不多但下面這幾個一旦定錯后面整站鏡像會放大成災(zāi)難。參數(shù)默認(rèn)值作用我一般怎么定project_folder當(dāng)前目錄產(chǎn)物根目錄掛到獨立數(shù)據(jù)盤別放代碼倉庫里project_name按 URL 生成本次任務(wù)子目錄日期_slug歸檔場景絕不復(fù)用overwriteFalse同名任務(wù)是否覆蓋調(diào)試True正式歸檔Falsedelay0請求間隔秒目標(biāo)站有頻控就調(diào)到 0.51.0threadedFalse是否多線程下載單頁無所謂整站建議關(guān)zip_projectFalse抓完是否打包成 zip需要交付單個文件時開delay這個參數(shù)值得單獨說一句。它控制的是每次請求之間的等待看起來不起眼但在整站鏡像里是決定你會不會被目標(biāo)站限流的關(guān)鍵。很多人第一次跑整站就把delay設(shè)成 0、threaded開成 True結(jié)果前兩百個請求很順第三百個開始全變 429后面抓回來的全是錯誤頁還得清空重來。3. 整站鏡像max_depth 與域名邊界決定你抓到的是站點還是垃圾場單頁跑通之后save_website的誘惑很大——一行調(diào)用抓一整個站。但整站鏡像的本質(zhì)是「從一個入口出發(fā)做廣度優(yōu)先遍歷」你不畫邊界它就會順著分頁、日歷、標(biāo)簽、搜索參數(shù)一路爬下去最后抓回來的東西和你想歸檔的內(nèi)容可能只重合三成。這一章講的就是怎么畫這個邊界。3.1 save_website 和 save_webpage 的差別不在抓多抓少兩者真正的差別在于「有沒有 URL 隊列」。save_webpage是一次性的解析當(dāng)前頁、下載依賴、改寫、結(jié)束不關(guān)心頁面里指向的其他 HTML。save_website維護(hù)一個待抓隊列每抓到一個 HTML 就從中提取站內(nèi)鏈接判斷是否在白名單內(nèi)、是否超過深度、是否命中黑名單通過了才入隊。這個機(jī)制帶來兩個直接后果。第一深度是相對入口頁計算的入口頁算第 0 層它鏈出去的算第 1 層max_depth3意味著最多跟三層再深的頁面不會被抓。第二去重完全依賴 URL 字符串同一個頁面如果有?fromhome和?fromlist兩個入口會被當(dāng)成兩個不同頁面各抓一遍產(chǎn)物里出現(xiàn)兩份內(nèi)容相同、路徑不同的 HTML。這一點在 CMS 站點上特別常見。所以整站鏡像的第一件事不是調(diào)深度而是想清楚「哪些 URL 形態(tài)是同一個頁面的不同馬甲」把它們?nèi)M(jìn)黑名單。3.2 用 allowed_domains 和 blacklist_urls 畫一個抓取圍欄下面這份調(diào)用是我在歸檔一個內(nèi)容站時的常用配置注釋寫得比較細(xì)可以直接照著改from pywebcopy import save_website save_website( urlhttps://demo-site.test/, project_folder./mirror, project_namedemo_site_full, # 從入口算起最多跟三層再深基本是分頁和日歷價值低且量大 max_depth3, # 域名白名單寫域名不寫 URL子域要單獨列出來 allowed_domains[demo-site.test, static.demo-site.test], # 正則黑名單注意把點號轉(zhuǎn)義否則 . 會匹配任意字符 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, # 一秒一個請求禮貌且不容易被限流 threadedFalse, # 大站關(guān)掉多線程隊列順序更可控 overwriteFalse, )allowed_domains是一個常見翻車點。它的語義是「允許抓取的域名」不包含主域之外的 CDN 域名時頁面里那些托管在 CDN 上的圖片可能抓不到。穩(wěn)妥做法是先把頁面里的資源域名掃一遍把靜態(tài)資源域也加進(jìn)去。至于資源抓取是否嚴(yán)格受這個白名單約束不同版本行為有差異所以最終還是要靠產(chǎn)物驗收來判斷別把它當(dāng)成鐵律。blacklist_urls用的是正則匹配匹配對象是完整 URL。寫的時候把/logout、/search?、/calendar/這幾類先排掉能省掉一大半無效請求。帶查詢串的 URL 記得把?也轉(zhuǎn)義進(jìn)去否則只匹配到路徑部分。3.3 delay 和 threaded 的取舍限速比并發(fā)重要整站鏡像最常見的誤區(qū)是把「抓得快」當(dāng)成目標(biāo)。實際上你真正要的是「抓得全且不重來」而重來的成本遠(yuǎn)高于慢一點的成本。配置組合適用場景風(fēng)險threadedFalse, delay0.5~1.0絕大多數(shù)整站歸檔慢但產(chǎn)物完整、可復(fù)現(xiàn)threadedFalse, delay0本地起服務(wù)測試對真實站點不要這么干threadedTrue, delay1.0大型靜態(tài)站、內(nèi)網(wǎng)環(huán)境隊列順序亂日志難對賬threadedTrue, delay0不推薦極易觸發(fā)限流抓到大量錯誤頁我自己的習(xí)慣是第一次跑永遠(yuǎn)用單線程加 1 秒間隔先抓個二三十頁看看產(chǎn)物質(zhì)量和日志確認(rèn)沒問題再決定要不要提速。提速的方式我傾向于「分批跑」而不是「調(diào)高并發(fā)」——把站點按欄目拆成多個任務(wù)每個任務(wù)用不同的project_name跑完再合并。這樣任何一個批次失敗損失都是局部可重跑的。還有一點容易被忽略delay作用的是請求之間的間隔但整站鏡像里有一部分耗時是資源下載那部分如果不走同一個限速器實際壓力可能比你預(yù)期的大。所以跑的時候盯著目標(biāo)站的響應(yīng)碼看一旦出現(xiàn) 429 或 503 的批量出現(xiàn)立刻停把delay翻倍再繼續(xù)。3.4 robots 與 bypass_robots 的邊界pywebcopy 有一個bypass_robots參數(shù)含義是抓取時是否忽略目標(biāo)站的 robots.txt 限制。這個參數(shù)的默認(rèn)值是False也就是默認(rèn)遵守。我的建議很明確除了你自己擁有或者明確獲得授權(quán)的站點其他場景一律保持默認(rèn)。robots.txt 表達(dá)的是站點運營方對爬蟲的意愿繞過它既可能違反站點條款也會讓你在對方日志里變成明顯的異常流量。歸檔公開內(nèi)容時正確的做法是先看一眼目標(biāo)站的 robots.txt瀏覽器直接訪問/robots.txt就能看確認(rèn)你要抓的路徑不在禁止列表里再按delay限速慢跑。還有一層現(xiàn)實考慮即便技術(shù)上繞過了對方一旦識別出高頻訪問封的是 IP 段你的整個抓取任務(wù)會從某一刻起全部返回 403而你已經(jīng)抓下來的半成品還得手工清理。這筆賬怎么算都不劃算。4. 避坑與排查五條用真實故障換來的記錄這一章里的每一條都是我在不同項目里實實在在撞過的。按「現(xiàn)象 → 原因 → 解決」寫方便你對照自己的報錯直接定位。4.1 頁面能打開但樣式全丟、圖片全裂現(xiàn)象HTML 雙擊能打開正文文字也在但整頁沒有排版控制臺里一堆 404指向的路徑形如./_internal/xxx/default.css實際磁盤上沒有這個文件。原因CSS 文件內(nèi)部的url(...)引用是相對于 CSS 文件自身位置的不是相對于 HTML。pywebcopy 在改寫 CSS 內(nèi)容時如果import形成了多層嵌套或者 CSS 里用了url(../fonts/a.woff2)這種跨級相對路徑改寫結(jié)果可能算錯基準(zhǔn)目錄導(dǎo)致資源被下載到了另一個位置而引用路徑指向空處。解決先手工確認(rèn)基準(zhǔn)。打開產(chǎn)物里的 CSS 文件搜索url(看改寫后的路徑再對照磁盤上資源實際所在目錄兩者一比對就知道偏移在哪。如果只是少量文件對不上寫個腳本按「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ù)assets_dir要指向你實際發(fā)現(xiàn)資源所在的目錄跑之前先find一遍確認(rèn)。4.2 抓回來一片空白HTML 里只有一個空的掛載點現(xiàn)象產(chǎn)物 HTML 打開是白屏查看源碼只有div idapp/div和幾個 script 標(biāo)簽正文一個字都沒有。原因目標(biāo)是單頁應(yīng)用正文由 JS 在瀏覽器里渲染出來服務(wù)器返回的原始 HTML 本身就是空的。pywebcopy 拿到的是服務(wù)器響應(yīng)不是渲染后的 DOM所以它抓到的就是那個空殼。解決在 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之后有兩條路一是寫入本地臨時文件起一個python -m http.server讓 pywebcopy 從這個本地地址抓這樣資源引用還能正常解析二是自己解析這份 HTML 把資源抓全完全繞開 pywebcopy 的抓取層。前者改動小后者可控性強(qiáng)我一般先用前者快速驗證。4.3 一批圖片落地后只剩一張文件名互相覆蓋現(xiàn)象頁面引用了logo.png?v1、logo.png?v2、logo.png?v3三個版本產(chǎn)物目錄里只有一張logo.png頁面上三個位置顯示的是同一張圖。原因落盤時文件名通常取自 URL 的 path 部分查詢串被丟掉了。三個 URL 的 path 完全相同自然寫到同一個文件后寫的覆蓋先寫的。解決抓取前先自己把資源本地化用「path 查詢串哈?！股晌ㄒ晃募膶?HTML 里的引用為相對路徑然后再讓 pywebcopy 處理頁面。這樣 pywebcopy 看到的已經(jīng)是本地相對引用不會再重復(fù)下載也不會撞名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算出相對當(dāng)前工作目錄的路徑所以調(diào)用這個函數(shù)時的工作目錄要和后續(xù) pywebcopy 的project_folder保持同一基準(zhǔn)否則改寫出來的相對路徑會偏。4.4 中文全是亂碼英文正常現(xiàn)象抓下來的頁面中文變成???–?這種字符英文和數(shù)字完全正常。原因目標(biāo)站響應(yīng)頭里沒給charset或者給了一個錯誤的默認(rèn)值比如ISO-8859-1而頁面實際是 GBK 或 UTF-8 編碼。requests 在沒有明確聲明時會按 HTTP 規(guī)范回退到 ISO-8859-1解出來就是亂碼。解決抓之前先探一次編碼再決定怎么傳。探測代碼如下import requests resp requests.get(https://demo-site.test/news/legacy.html, timeout10) # 先看響應(yīng)頭聲明再看內(nèi)容推測兩者不一致時以推測為準(zhǔn) print(declared:, resp.encoding) print(detected:, resp.apparent_encoding)較新版本的 pywebcopy 支持傳入編碼相關(guān)的關(guān)鍵字參數(shù)把探測到的值傳進(jìn)去即可。如果你的版本不認(rèn)這個參數(shù)退路是先按正確編碼把內(nèi)容寫成臨時 HTML 文件本地起一個 http 服務(wù)讓 pywebcopy 從本地地址抓——本地服務(wù)的響應(yīng)頭你可以完全控制編碼問題就繞過去了。4.5 整站跑到一半卡住內(nèi)存持續(xù)上漲現(xiàn)象任務(wù)跑到幾百個頁面之后速度明顯變慢進(jìn)程內(nèi)存一路漲到幾個 G最后要么被系統(tǒng)殺掉要么一直掛在那里不動。原因遞歸隊列沒有做上限控制加上threadedTrue時多個線程同時往隊列里塞 URL去重表膨脹再加上每個頁面的 DOM 對象沒有被及時釋放累積起來就是內(nèi)存雪崩。站點越大、重復(fù)入口越多這個問題越明顯。解決三個動作一起做。第一關(guān)掉多線程threadedFalse把并發(fā)壓力換成可預(yù)測的順序執(zhí)行。第二把blacklist_urls補(bǔ)齊尤其是帶分頁參數(shù)的?page、帶排序參數(shù)的?sort這些是隊列膨脹的主要來源。第三分批跑按欄目或按字母區(qū)間拆成多個任務(wù)每個任務(wù)用獨立的project_name跑完再合并目錄。批量跑的時候在外面套一層循環(huán)單任務(wù)失敗不影響后續(xù)日志里記清楚哪一批失敗了好補(bǔ)跑。注意整站鏡像前先估算體量。用max_depth1試跑一次看單頁平均產(chǎn)物大小和頁面數(shù)乘以預(yù)估總頁數(shù)得出來的數(shù)字如果超過磁盤剩余空間的七成就先拆批次。5. 封裝成能反復(fù)用的鏡像工具批處理、增量與產(chǎn)物校驗單次調(diào)用解決不了「每周歸檔一次」這種需求。真正要長期用得往上包一層命令行入口負(fù)責(zé)批量調(diào)度狀態(tài)庫負(fù)責(zé)跳過沒變的頁面校驗?zāi)_本負(fù)責(zé)在交付前兜底。這三塊加起來不到兩百行但能把返工率壓下去一大截。5.1 用 argparse 包一層命令行一次傳多個入口核心訴求是「一條命令跑完一批 URL單個失敗不中斷」。下面這版實現(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)頁或站點) p.add_argument(urls, nargs, help入口 URL可以傳多個) p.add_argument(-o, --out, default./mirror, help產(chǎn)物根目錄) p.add_argument(-n, --name, defaultNone, help任務(wù)名默認(rèn)按時間戳生成) p.add_argument(-d, --depth, typeint, default1, help1 表示只抓單頁大于 1 表示按深度遞歸) p.add_argument(--delay, typefloat, default0.8, help請求間隔秒) 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: # 單個任務(wù)失敗只記錄不中斷整批 print(f[fail] {url}: {exc}) if __name__ __main__: main()幾個設(shè)計取舍值得說明。depth1走單頁分支、大于 1 走整站分支是為了讓同一個命令既能做快速快照又能做深度歸檔不用記兩套參數(shù)。urlsplit(url).netloc直接把入口域名當(dāng)白名單省掉手填但如果目標(biāo)站的資源在獨立 CDN 域上這個默認(rèn)值會漏抓所以正式場景還是建議加一個--allow-domain參數(shù)手動補(bǔ)。異常捕獲用寬泛的Exception在批處理場景里是對的——你寧可吞掉一條錯誤日志也不愿意因為第 3 個 URL 掛了導(dǎo)致后面 50 個沒跑。5.2 用 SQLite 記狀態(tài)跳過沒變化的頁面每周歸檔一次同樣的站點如果每次都全量重抓時間和帶寬都浪費在沒變的頁面上。判斷頁面變沒變最可靠的是服務(wù)端給的ETag和Last-Modified這兩個頭在 HEAD 請求里就能拿到成本極低。先建一張狀態(tài)表主鍵是 URL記錄兩個校驗值和時間戳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)先級更高是因為它通常是對內(nèi)容做哈希算出來的比時間戳精確有些服務(wù)器只給其中一個所以兩個都要兼容。注意etag and ...這個寫法etag為空字符串時直接短路返回False避免把「服務(wù)端沒給 ETag」誤判成「內(nèi)容變了」而觸發(fā)全量重抓。配套的調(diào)度循環(huán)大致是先對每個 URL 發(fā) HEAD 請求拿兩個頭查庫判斷要不要抓要抓才調(diào) pywebcopy抓完把新值寫回去。整站鏡像場景下這套邏輯要放在 URL 入隊的那一層而不是抓完再判斷否則省不下請求。5.3 交付前的三道校驗別讓殘缺產(chǎn)物出門抓完之后最怕的是「看起來抓完了其實缺了一半」。寫一個校驗函數(shù)把產(chǎn)物目錄里所有 HTML 的相對引用掃一遍檢查目標(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 # 去掉查詢串和錨點再解碼百分號編碼才是真實的文件路徑 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三個細(xì)節(jié)決定這個腳本準(zhǔn)不準(zhǔn)。第一過濾協(xié)議前綴時要帶上javascript:和mailto:否則一堆內(nèi)聯(lián)腳本會被誤報。第二必須unquote因為 HTML 里的中文路徑通常是百分號編碼的不還原就會算出不存在的路徑。第三用limit截斷站點大的時候缺失項可能有幾千條全部打印出來反而看不到重點先看前三十條足夠判斷是系統(tǒng)性問題還是零星遺漏。校驗結(jié)果怎么用如果缺失集中在某幾類資源上比如所有字體都缺說明是解析層的系統(tǒng)性問題回到第 4 章對應(yīng)條目排查如果缺失是零散的、每次跑的都不一樣多半是網(wǎng)絡(luò)超時導(dǎo)致的下載失敗把delay調(diào)大重跑一遍缺失的部分即可。6. 進(jìn)階把預(yù)渲染和特性補(bǔ)刀接進(jìn)同一條流水線走到這一步pywebcopy 能覆蓋的場景已經(jīng)比較清楚了靜態(tài)渲染的內(nèi)容站、文檔站、活動頁歸檔幾行代碼就能出可用產(chǎn)物。剩下的短板集中在兩類一類是 JS 渲染一類是 HTML 特性覆蓋不全這兩塊都可以在調(diào)用它之前用幾十行代碼補(bǔ)上。先看一張對比表把不同頁面類型的推薦路徑列清楚省得每次都重新想頁面類型直接 save_webpage預(yù)渲染后再抓說明服務(wù)端渲染的內(nèi)容頁可用不必要首選方案成本最低靜態(tài)文檔 / 博客可用不必要注意 CSS 里的字體和 import單頁應(yīng)用產(chǎn)物為空殼必選先拿到渲染后 DOM 再抓重圖片的電商詳情頁部分可用建議srcset 多分辨率容易漏抓需要登錄的頁面不可用不可用會話態(tài)不在這個工具的射程內(nèi)預(yù)渲染那一步在第 4 章已經(jīng)給過代碼這里補(bǔ)一個把兩者串起來的做法先用無頭瀏覽器拿到渲染后的 HTML寫到一個臨時目錄起一個本地靜態(tài)服務(wù)再把本地地址交給 pywebcopy。這樣 pywebcopy 的解析和改寫能力仍然能用上同時它面對的不再是空殼。落地時注意本地服務(wù)的端口要固定別用隨機(jī)端口否則日志里的產(chǎn)物路徑每次都不一樣排查時對不上號。另一個高頻遺漏是srcset。響應(yīng)式圖片會給多個分辨率候選pywebcopy 對這類屬性的處理在不同版本上不一致穩(wěn)妥做法是在抓之前把srcset壓成一個src只保最大的一張import re def flatten_srcset(html: str) - str: 把 srcset 壓成單個 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)這個替換是粗暴的它不管原來的img上有沒有src直接覆蓋。生產(chǎn)環(huán)境里要先判斷節(jié)點是否已有src有的話只在srcset存在時才改沒有的話補(bǔ)一個。取最后一張是因為大多數(shù)站點的srcset按從小到大排列最后一張分辨率最高離線歸檔場景下清晰度比體積重要。最后說個我自己的習(xí)慣每次歸檔任務(wù)開始前先在紙上寫三行——這次要抓什么、抓到什么程度算完成、產(chǎn)物交給誰。這三行寫不出來說明需求還沒想清楚這時候調(diào)參數(shù)都是瞎調(diào)。鏡像網(wǎng)頁這件事工具只占三成剩下七成是想清楚邊界。前面那些踩坑記錄有一半是因為我一開始沒寫這三行。希望幫到你。本文還有配套的精品資源點擊獲取