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