歸檔工作流：TypeScript+油猴+EPUB的工程化實(shí)踐)
1. 這不是“爬蟲工具”而是一套可維護(hù)、可擴(kuò)展的小說(shuō)歸檔工作流你搜“novel-downloader”時(shí)看到的多半是零散腳本、失效鏈接、報(bào)錯(cuò)截圖或是某論壇里一句“親測(cè)可用”。但真正用過(guò)半年以上的人會(huì)發(fā)現(xiàn)所謂“神器”從來(lái)不是點(diǎn)一下就完事的黑盒——它是一整套圍繞小說(shuō)內(nèi)容獲取、結(jié)構(gòu)化處理、長(zhǎng)期歸檔而設(shè)計(jì)的工程化方案。核心關(guān)鍵詞novel-downloader、TypeScript、油猴腳本、EPUB其實(shí)指向四個(gè)不可割裂的環(huán)節(jié)規(guī)則驅(qū)動(dòng)的內(nèi)容抓取層油猴→ 類型安全的邏輯編排層TypeScript→ 網(wǎng)站適配的插件化架構(gòu)novel-downloader→ 標(biāo)準(zhǔn)化交付與再加工層EPUB。這不是給小白準(zhǔn)備的“一鍵下載器”而是為有持續(xù)閱讀歸檔需求的讀者、數(shù)字人文研究者、電子書收藏愛(ài)好者、甚至小規(guī)模內(nèi)容聚合平臺(tái)搭建者提供的一套可審計(jì)、可調(diào)試、可復(fù)用的技術(shù)棧。它解決的不是“能不能下”而是“下得準(zhǔn)不準(zhǔn)、結(jié)構(gòu)對(duì)不對(duì)、格式穩(wěn)不穩(wěn)、后續(xù)好不好用”。比如你從起點(diǎn)中文網(wǎng)抓一本百萬(wàn)字長(zhǎng)篇章節(jié)順序錯(cuò)亂、封面丟失、作者信息為空——這不算成功而用這套方案你拿到的是帶完整元數(shù)據(jù)ISBN模擬號(hào)、出版時(shí)間戳、作者簡(jiǎn)介區(qū)塊、章節(jié)標(biāo)題自動(dòng)標(biāo)準(zhǔn)化“第123章”→“第123章 風(fēng)起青萍末”、正文無(wú)廣告段落、封面圖嵌入OPF文件的EPUB 3.0標(biāo)準(zhǔn)包且整個(gè)過(guò)程可在瀏覽器控制臺(tái)逐行調(diào)試。它面向的不是“臨時(shí)下載一次”的用戶而是需要每月穩(wěn)定歸檔50本、跨10個(gè)網(wǎng)站、持續(xù)3年以上的實(shí)踐者。如果你正被“下載后要手動(dòng)刪廣告”“章節(jié)名全是‘最新章節(jié)’”“EPUB打開(kāi)后目錄空白”這些問(wèn)題反復(fù)消耗時(shí)間那這篇指南就是為你寫的——它不教你“怎么裝油猴”而是告訴你為什么必須用TypeScript重寫解析器、為什么baseurl棄用警告實(shí)際暴露了架構(gòu)隱患、為什么Calibre不是終點(diǎn)而是中間站。2. 項(xiàng)目整體設(shè)計(jì)與技術(shù)選型邏輯拆解2.1 為什么放棄Python爬蟲選擇瀏覽器端TypeScript方案很多人第一反應(yīng)是“小說(shuō)下載寫個(gè)Python爬蟲不就行了”——這恰恰是踩坑的起點(diǎn)。我試過(guò)用requestsBeautifulSoup抓晉江、紅袖、豆瓣閱讀兩周后全部失效。原因很現(xiàn)實(shí)反爬策略升級(jí)快現(xiàn)代小說(shuō)站90%以上采用動(dòng)態(tài)渲染Vue/ReactHTML源碼里只有空div真實(shí)章節(jié)內(nèi)容由JS異步加載并插入DOM。requests拿不到正文必須上Selenium或Playwright但后者啟動(dòng)慢、內(nèi)存占用高、無(wú)法集成到瀏覽器工作流中登錄態(tài)綁定深起點(diǎn)需cookietoken雙重校驗(yàn)知乎鹽選需微信掃碼豆瓣需OAuth2.0授權(quán)碼。服務(wù)端爬蟲要模擬完整登錄流程而瀏覽器環(huán)境天然持有用戶當(dāng)前會(huì)話調(diào)試成本懸殊在Chrome開(kāi)發(fā)者工具里右鍵“Break on subtree modifications”立刻定位到章節(jié)內(nèi)容插入的JS調(diào)用棧而在Python里你要逆向分析混淆后的webpack bundle耗時(shí)3小時(shí)可能只找到一個(gè)加密參數(shù)生成函數(shù)。所以novel-downloader的核心設(shè)計(jì)原則是所有解析邏輯運(yùn)行在用戶瀏覽器內(nèi)復(fù)用目標(biāo)網(wǎng)站已加載的JS上下文和登錄態(tài)。油猴腳本Tampermonkey是唯一滿足該原則的成熟載體——它能注入代碼、監(jiān)聽(tīng)DOM變化、攔截XHR請(qǐng)求、讀取localStorage且支持模塊化開(kāi)發(fā)。而TypeScript的選擇源于三個(gè)硬性需求多人協(xié)作適配小說(shuō)網(wǎng)站規(guī)則常由社區(qū)貢獻(xiàn)如GitHub上novel-downloader的rules倉(cāng)庫(kù)沒(méi)有類型定義新人改一個(gè)selector就導(dǎo)致全站解析崩潰錯(cuò)誤提前暴露chapterListSelector: string比chapterListSelector #list a更安全——當(dāng)網(wǎng)站把#list改成.catalog時(shí)TypeScript編譯直接報(bào)錯(cuò)而非運(yùn)行時(shí)報(bào)Cannot read property href of nullIDE智能提示剛需解析器要處理“章節(jié)標(biāo)題提取”“正文清洗”“圖片懶加載轉(zhuǎn)真實(shí)URL”等12類通用操作每個(gè)操作都有輸入/輸出約束。用any類型寫100行后自己都看不懂data到底是什么結(jié)構(gòu)用interface Chapter { title: string; url: string; content: string[] }VS Code自動(dòng)補(bǔ)全chapter.content.map(...)效率提升3倍。提示TypeScript不是“為了用而用”。當(dāng)你看到options.baseUrl棄用警告時(shí)別急著改配置——這是TypeScript編譯器在提醒你當(dāng)前架構(gòu)把所有網(wǎng)站共用的URL前綴硬編碼在配置里違反了“開(kāi)閉原則”。正確做法是讓每個(gè)網(wǎng)站規(guī)則對(duì)象自行實(shí)現(xiàn)getChapterUrl(slug: string): string方法baseUrl變成可選參數(shù)這才是類型系統(tǒng)真正想幫你規(guī)避的設(shè)計(jì)債。2.2 油猴腳本為何是不可替代的入口層有人問(wèn)“Electron打包成桌面App不行嗎”——可以但代價(jià)巨大。我們對(duì)比三種部署形態(tài)方案啟動(dòng)速度登錄態(tài)復(fù)用調(diào)試便利性規(guī)則更新頻率典型失敗場(chǎng)景油猴腳本100ms? 原生復(fù)用? 控制臺(tái)實(shí)時(shí)debug? 用戶點(diǎn)擊更新按鈕網(wǎng)站CSS選擇器變更腳本自動(dòng)失效Python服務(wù)端2~5s? 需單獨(dú)維護(hù)cookie池? 日志查錯(cuò)無(wú)法斷點(diǎn)? 需重啟服務(wù)IP被封請(qǐng)求返回403Electron桌面版3~8s?? 需注入瀏覽器cookie?? 需開(kāi)啟遠(yuǎn)程調(diào)試端口? 打包新版本發(fā)用戶Windows Defender誤報(bào)為木馬油猴的本質(zhì)是瀏覽器能力的標(biāo)準(zhǔn)化封裝。novel-downloader的油猴入口腳本main.user.ts只做三件事檢測(cè)當(dāng)前頁(yè)面是否匹配已注冊(cè)的網(wǎng)站規(guī)則如location.hostname www.qidian.com動(dòng)態(tài)導(dǎo)入對(duì)應(yīng)網(wǎng)站的TypeScript規(guī)則模塊import(./rules/qidian).then(rule rule.init())注入U(xiǎn)I按鈕懸浮窗/右鍵菜單觸發(fā)下載流程。這個(gè)設(shè)計(jì)讓“新增一個(gè)網(wǎng)站支持”變成純前端工作只需在/rules目錄下新建novelread.ts實(shí)現(xiàn)init()、getBookInfo()、getChapterList()三個(gè)接口編譯后油猴自動(dòng)識(shí)別。我們團(tuán)隊(duì)曾用2小時(shí)為小眾站“看書網(wǎng)”添加支持而Python方案需要重寫HTTP客戶端、重配代理池、重測(cè)UA輪換策略——這就是架構(gòu)差異帶來(lái)的生產(chǎn)力鴻溝。2.3 EPUB作為交付標(biāo)準(zhǔn)的深層考量為什么最終輸出一定是EPUB而不是TXT或PDF因?yàn)镋PUB是唯一同時(shí)滿足閱讀體驗(yàn)、元數(shù)據(jù)承載、再加工友好性的開(kāi)放標(biāo)準(zhǔn)。具體看三個(gè)維度閱讀體驗(yàn)EPUB本質(zhì)是zip壓縮包內(nèi)含XHTML正文、CSS樣式、字體文件、NCX/OPF導(dǎo)航文件。Kindle、Apple Books、KOReader都能正確渲染分頁(yè)、目錄跳轉(zhuǎn)、字體縮放TXT純文本無(wú)章節(jié)錨點(diǎn)PDF固定版式在手機(jī)上需不斷縮放拖拽元數(shù)據(jù)承載OPF文件支持dc:title、dc:creator、dc:identifier等Dublin Core字段。我們?yōu)槊勘拘≌f(shuō)生成模擬ISBN如novel-downloader:qidian:123456789記錄抓取時(shí)間戳dc:date2024-06-15T14:22:33Z/dc:date甚至嵌入作者簡(jiǎn)介HTML區(qū)塊。這些信息在TXT里只能靠文件名約定《詭秘之主》-愛(ài)潛水的烏賊.txt極易丟失再加工友好性EPUB可被Calibre無(wú)損轉(zhuǎn)換為AZW3/MOBI用Sigil編輯HTML正文用epubcheck驗(yàn)證標(biāo)準(zhǔn)合規(guī)性。而PDF轉(zhuǎn)EPUB會(huì)丟失語(yǔ)義結(jié)構(gòu)TXT轉(zhuǎn)EPUB需手動(dòng)補(bǔ)全章節(jié)標(biāo)簽。注意不要用“EPUB在線編輯”類工具處理novel-downloader輸出。這類工具多基于WebAssembly解析對(duì)大文件5MB支持差且會(huì)清空OPF里的自定義元數(shù)據(jù)。實(shí)測(cè)一本120萬(wàn)字小說(shuō)EPUB含封面圖用Sigil打開(kāi)耗時(shí)8秒用在線編輯器上傳10分鐘超時(shí)。正確流程是——下載后立即用Calibre批量校驗(yàn)ebook-meta *.epub再按需轉(zhuǎn)格式。3. 核心細(xì)節(jié)解析與實(shí)操要點(diǎn)3.1 novel-downloader規(guī)則模塊的TypeScript接口設(shè)計(jì)novel-downloader的可擴(kuò)展性根植于其嚴(yán)格的TypeScript接口契約。所有網(wǎng)站規(guī)則必須實(shí)現(xiàn)NovelRule接口核心字段如下精簡(jiǎn)版interface NovelRule { // 網(wǎng)站標(biāo)識(shí)用于日志追蹤和緩存key id: string; // 匹配URL的正則支持多域名 match: RegExp[]; // 獲取書籍基礎(chǔ)信息標(biāo)題、作者、封面URL、簡(jiǎn)介 getBookInfo(): PromiseBookInfo; // 獲取章節(jié)列表返回有序的章節(jié)對(duì)象數(shù)組 getChapterList(): PromiseChapterItem[]; // 獲取單章內(nèi)容返回清洗后的HTML字符串不含廣告、導(dǎo)航欄 getChapterContent(url: string): Promisestring; // 可選處理封面圖支持base64或URL processCover?(coverUrl: string): Promisestring | ArrayBuffer; } interface BookInfo { title: string; author: string; coverUrl: string; description: string; // 自定義字段供EPUB元數(shù)據(jù)生成 publisher?: string; language?: string; } interface ChapterItem { title: string; url: string; // 章節(jié)序號(hào)用于EPUB目錄排序 index: number; }這個(gè)設(shè)計(jì)解決了三個(gè)關(guān)鍵問(wèn)題防錯(cuò)機(jī)制getChapterList()返回PromiseChapterItem[]TypeScript強(qiáng)制要求每個(gè)元素有title、url、index。如果某網(wǎng)站返回[{title: 第一章}]缺url編譯直接報(bào)錯(cuò)避免運(yùn)行時(shí)因undefined.href崩潰語(yǔ)義明確processCover?是可選方法但一旦實(shí)現(xiàn)就必須返回string | ArrayBuffer。這意味著你可以返回base64字符串data:image/jpeg;base64,...或二進(jìn)制ArrayBuffer供Node.js后端處理類型系統(tǒng)確保調(diào)用方能正確分支處理擴(kuò)展預(yù)留BookInfo里的publisher、language字段雖非必需但為后續(xù)對(duì)接圖書館編目系統(tǒng)如MARC21留出空間。當(dāng)我們?yōu)楣偶尽皣?guó)學(xué)寶典”添加規(guī)則時(shí)直接填入publisher: 中華書局EPUB生成時(shí)自動(dòng)寫入OPF。實(shí)操中我見(jiàn)過(guò)最典型的錯(cuò)誤是開(kāi)發(fā)者把getChapterContent()寫成同步函數(shù)返回string而非Promisestring。結(jié)果在抓取需要等待AJAX加載的網(wǎng)站如縱橫中文網(wǎng)時(shí)腳本拿到空字符串。TypeScript編譯器此時(shí)會(huì)報(bào)錯(cuò)Type string is not assignable to type Promisestring——這就是類型系統(tǒng)在救你命。3.2 油猴腳本的動(dòng)態(tài)模塊加載與錯(cuò)誤隔離novel-downloader的油猴入口腳本main.user.ts采用動(dòng)態(tài)import()加載規(guī)則模塊而非靜態(tài)import。這是為實(shí)現(xiàn)錯(cuò)誤隔離和按需加載// main.user.ts 關(guān)鍵片段 async function loadRuleForCurrentSite() { const hostname location.hostname; let ruleModule: typeof import(./rules/qidian) | null null; try { if (hostname.includes(qidian.com)) { ruleModule await import(./rules/qidian); } else if (hostname.includes(zongheng.com)) { ruleModule await import(./rules/zongheng); } else { console.warn(No rule found for ${hostname}); return; } // 調(diào)用規(guī)則初始化函數(shù) ruleModule.init(); } catch (error) { // 單個(gè)網(wǎng)站規(guī)則加載失敗不影響其他網(wǎng)站 console.error(Failed to load rule for ${hostname}:, error); alert(網(wǎng)站適配加載失敗請(qǐng)檢查網(wǎng)絡(luò)或稍后重試); } }這個(gè)設(shè)計(jì)帶來(lái)兩個(gè)實(shí)操優(yōu)勢(shì)故障域隔離假設(shè)zongheng.ts規(guī)則因網(wǎng)站改版報(bào)錯(cuò)qidian.ts仍可正常工作。用戶訪問(wèn)起點(diǎn)時(shí)完全無(wú)感知而靜態(tài)導(dǎo)入會(huì)導(dǎo)致整個(gè)油猴腳本崩潰體積可控所有規(guī)則模塊被打包成獨(dú)立chunk。用戶首次訪問(wèn)起點(diǎn)只下載qidian.js約12KB訪問(wèn)縱橫時(shí)再加載zongheng.js約8KB。若用靜態(tài)導(dǎo)入初始腳本體積達(dá)200KB影響油猴啟動(dòng)速度。實(shí)操心得動(dòng)態(tài)import路徑必須是字符串字面量./rules/qidian不能拼接變量./rules/ siteId。否則Webpack無(wú)法靜態(tài)分析會(huì)把所有規(guī)則打包進(jìn)一個(gè)大chunk。我們?cè)騣mport(./rules/ domainMap[hostname])導(dǎo)致首屏加載延遲3秒修正后恢復(fù)毫秒級(jí)響應(yīng)。3.3 EPUB生成的核心參數(shù)與Calibre集成技巧novel-downloader生成EPUB的過(guò)程分為兩階段前端結(jié)構(gòu)化數(shù)據(jù)組裝 → 后端EPUB文件生成。前端只產(chǎn)出JSON格式的書籍?dāng)?shù)據(jù)含章節(jié)HTML、元數(shù)據(jù)、封面base64后端用Node.js調(diào)用epub-gen庫(kù)生成EPUB文件。關(guān)鍵參數(shù)配置如下// EPUB生成配置Node.js端 const epubOptions { // 必須指定否則Calibre無(wú)法識(shí)別 title: bookInfo.title, author: bookInfo.author, // 模擬ISBN格式為novel-downloader:{siteId}:{bookId} identifier: novel-downloader:${rule.id}:${bookId}, // 語(yǔ)言代碼影響字體渲染 language: bookInfo.language || zh-CN, // 封面必須是base64字符串且包含MIME類型 cover: data:image/jpeg;base64,${coverBase64}, // 章節(jié)HTML數(shù)組每項(xiàng)為{title, data}data是清洗后的XHTML字符串 contents: chapterContents.map((c, i) ({ title: c.title, data: c.content, // 章節(jié)序號(hào)決定EPUB目錄順序 index: i 1 })), // 強(qiáng)制啟用EPUB 3.0標(biāo)準(zhǔn)支持MathML和音視頻 version: 3.0, // 輸出路徑 output: ${outputDir}/${sanitizeFilename(bookInfo.title)}.epub };這里有幾個(gè)易錯(cuò)點(diǎn)必須強(qiáng)調(diào)封面格式cover字段必須是完整的data URIdata:image/jpeg;base64,...不能只傳base64字符串。Calibre解析時(shí)會(huì)校驗(yàn)MIME類型傳錯(cuò)導(dǎo)致封面丟失章節(jié)HTML清洗c.content必須是嚴(yán)格XHTML格式閉合標(biāo)簽、小寫標(biāo)簽名。我們用DOMPurify.sanitize()清理但需額外配置DOMPurify.setConfig({ ALLOWED_TAGS: [p, br, h1, h2, h3, strong, em, img], ALLOWED_ATTR: [src, alt, style], // 移除所有on*事件防止XSS FORBID_TAGS: [script, iframe], });曾有用戶反饋“EPUB打開(kāi)后圖片不顯示”排查發(fā)現(xiàn)是原始HTML里img srcjavascript:alert(1)未被過(guò)濾Calibre安全策略直接屏蔽該圖片文件名安全化sanitizeFilename()函數(shù)需移除Windows非法字符\ / : * ? |和Unicode控制字符。我們用正則/[\\/:*?|]/g替換為空格再用encodeURIComponent()編碼避免下載后文件名亂碼。提示Calibre命令行轉(zhuǎn)換AZW3時(shí)務(wù)必加--no-default-epub-cover參數(shù)。novel-downloader生成的EPUB已內(nèi)置封面不加此參數(shù)Calibre會(huì)覆蓋原封面生成空白封面的AZW3。4. 完整實(shí)操流程與核心環(huán)節(jié)實(shí)現(xiàn)4.1 環(huán)境準(zhǔn)備從零搭建TypeScript開(kāi)發(fā)環(huán)境不要用“npm create vitelatest”——vite默認(rèn)配置對(duì)油猴腳本不友好。正確流程是初始化項(xiàng)目mkdir novel-downloader cd novel-downloader npm init -y npm install --save-dev typescript types/tampermonkey webpack webpack-cli ts-loader npx tsc --init修改tsconfig.json關(guān)鍵配置{ compilerOptions: { target: ES2018, module: ESNext, lib: [ES2018, DOM], strict: true, skipLibCheck: true, forceConsistentCasingInFileNames: true, moduleResolution: node, resolveJsonModule: true, isolatedModules: true, outDir: ./dist, rootDir: ./src, declaration: true, sourceMap: true, // 油猴腳本必須用AMD或System但Webpack兼容性更好 module: ESNext }, include: [src/**/*], exclude: [node_modules] }配置Webpackwebpack.config.jsconst path require(path); module.exports { entry: ./src/main.user.ts, output: { path: path.resolve(__dirname, dist), filename: novel-downloader.user.js, // 油猴腳本必須是IIFE格式 libraryTarget: var, library: novelDownloader }, resolve: { extensions: [.ts, .js] }, module: { rules: [ { test: /\.ts$/, use: ts-loader, exclude: /node_modules/ } ] }, plugins: [ // 注入油猴元數(shù)據(jù) new (require(webpack).BannerPlugin)({ banner: // UserScript// name 小說(shuō)下載神器 // namespace https://github.com/yourname/novel-downloader // version 1.0.0 // description 一鍵保存100網(wǎng)站小說(shuō) // author You // match://.qidian.com/* // match://.zongheng.com/* // grant unsafeWindow // grant GM_xmlhttpRequest // grant GM_setClipboard // /UserScript, raw: true }) ] };關(guān)鍵點(diǎn)match指令必須顯式列出支持的域名油猴根據(jù)此匹配觸發(fā)腳本GM_xmlhttpRequest是跨域請(qǐng)求必需權(quán)限unsafeWindow用于訪問(wèn)網(wǎng)站全局變量如起點(diǎn)的Qidian對(duì)象。 3. **創(chuàng)建規(guī)則目錄結(jié)構(gòu)**src/ ├── main.user.ts # 油猴入口 ├── rules/ │ ├── qidian.ts # 起點(diǎn)規(guī)則 │ ├── zongheng.ts # 縱橫規(guī)則 │ └── base.ts # 抽象基類含通用清洗方法 └── utils/ ├── dom.ts # DOM操作工具 └── epub.ts # EPUB生成輔助函數(shù)base.ts定義abstract class BaseRule implements NovelRule封裝cleanText()、extractTitleFromUrl()等通用方法子類繼承即可復(fù)用。 ### 4.2 起點(diǎn)中文網(wǎng)qidian.com規(guī)則實(shí)現(xiàn)詳解 以起點(diǎn)為例展示如何將網(wǎng)站結(jié)構(gòu)轉(zhuǎn)化為TypeScript規(guī)則 **第一步分析頁(yè)面結(jié)構(gòu)** - 書籍主頁(yè)URLhttps://book.qidian.com/info/1010761094/ - 章節(jié)列表頁(yè)https://book.qidian.com/info/1010761094/catalog - 單章URLhttps://read.qidian.com/chapter/_JkYdVtLQmKfUw2bXlGqjA/1010761094/1010761094_1010761094_1010761094.html **第二步編寫qidian.ts** typescript import { BaseRule } from ../base; import { BookInfo, ChapterItem } from ../types; export class QidianRule extends BaseRule { id qidian; match [/qidian\.com/]; async getBookInfo(): PromiseBookInfo { // 起點(diǎn)書籍信息在window._INITIAL_STATE中是JSON字符串 const state JSON.parse( document.querySelector(#__NEXT_DATA__)?.textContent || {} ); const book state.props.pageProps?.dehydratedState?.queries?.[0]?.state?.data; return { title: book?.bookName || 未知書名, author: book?.authorName || 未知作者, coverUrl: book?.cover || , description: book?.intro || , publisher: 閱文集團(tuán) }; } async getChapterList(): PromiseChapterItem[] { // 起點(diǎn)章節(jié)列表由JS動(dòng)態(tài)渲染需等待DOM出現(xiàn) await this.waitForElement(.chapter-list); const chapters: ChapterItem[] []; document.querySelectorAll(.chapter-list li a).forEach((a, index) { chapters.push({ title: a.textContent?.trim() || 第${index 1}章, url: a.href, index: index 1 }); }); return chapters; } async getChapterContent(url: string): Promisestring { // 起點(diǎn)單章頁(yè)需等待#content容器加載 const response await fetch(url); const html await response.text(); const parser new DOMParser(); const doc parser.parseFromString(html, text/html); // 提取正文移除廣告、導(dǎo)航、評(píng)論區(qū) const content doc.querySelector(#content)?.innerHTML || ; return this.cleanText(content); } } export function init() { new QidianRule().init(); }第三步關(guān)鍵技巧說(shuō)明waitForElement()起點(diǎn)章節(jié)列表是滾動(dòng)加載document.querySelectorAll()可能返回空數(shù)組。我們實(shí)現(xiàn)一個(gè)輪詢函數(shù)protected async waitForElement(selector: string, timeout 5000) { const start Date.now(); while (Date.now() - start timeout) { if (document.querySelector(selector)) return; await new Promise(r setTimeout(r, 100)); } throw new Error(Element ${selector} not found within ${timeout}ms); }cleanText()繼承自BaseRule移除常見(jiàn)廣告節(jié)點(diǎn)protected cleanText(html: string): string { const temp document.createElement(div); temp.innerHTML html; // 移除廣告div temp.querySelectorAll(.ad, .advertisement, [id*ad], [class*banner]).forEach(el el.remove()); // 移除“本章說(shuō)”評(píng)論區(qū) temp.querySelector(.comment-section)?.remove(); // 清理多余空行 return temp.innerHTML.replace(/\n\s*\n/g, \n); }fetch()替代GM_xmlhttpRequest起點(diǎn)允許CORS直接用原生fetch更簡(jiǎn)潔。若遇跨域限制再切回GM_xmlhttpRequest。4.3 EPUB文件生成與Calibre自動(dòng)化處理前端生成JSON數(shù)據(jù)后需通過(guò)Node.js服務(wù)生成EPUB。我們用Express搭建輕量APInpm install express epub-gen fs-extraserver.js核心邏輯const express require(express); const epubGen require(epub-gen); const fs require(fs-extra); const app express(); app.use(express.json()); app.post(/generate-epub, async (req, res) { const { bookData } req.body; // 前端POST的JSON try { // 生成EPUB文件 await new epubGen({ title: bookData.title, author: bookData.author, identifier: bookData.identifier, language: bookData.language || zh-CN, cover: bookData.cover, contents: bookData.contents, version: 3.0, output: ./output/${bookData.title}.epub }).generate(); // 用Calibre命令行轉(zhuǎn)AZW3需提前安裝Calibre const azw3Path ./output/${bookData.title}.azw3; const epubPath ./output/${bookData.title}.epub; const calibreCmd ebook-convert ${epubPath} ${azw3Path} --no-default-epub-cover; require(child_process).execSync(calibreCmd); res.json({ success: true, epubUrl: /output/${bookData.title}.epub, azw3Url: /output/${bookData.title}.azw3 }); } catch (error) { res.status(500).json({ error: error.message }); } }); app.listen(3000, () console.log(Server running on http://localhost:3000));Calibre安裝與配置要點(diǎn)下載地址https://calibre-ebook.com/download選對(duì)應(yīng)系統(tǒng)版本W(wǎng)indows安裝后將C:\Program Files\Calibre2\加入系統(tǒng)PATHLinux/macOS用sudo apt install calibreUbuntu或brew install calibremacOS關(guān)鍵參數(shù)--no-default-epub-cover必須加否則Calibre會(huì)用默認(rèn)封面覆蓋novel-downloader生成的封面若需批量處理用ebook-convert配合shell腳本# batch-convert.sh for epub in ./output/*.epub; do azw3${epub%.epub}.azw3 ebook-convert $epub $azw3 --no-default-epub-cover done4.4 油猴腳本發(fā)布與用戶安裝流程開(kāi)發(fā)完成后需發(fā)布為用戶可安裝的.user.js文件Webpack構(gòu)建npx webpack --mode production輸出dist/novel-downloader.user.js即最終油猴腳本。發(fā)布到GitHub Pages推薦創(chuàng)建GitHub倉(cāng)庫(kù)novel-downloader將dist/novel-downloader.user.js提交到main分支Settings → Pages → Source選main branch /dist訪問(wèn)https://username.github.io/novel-downloader/novel-downloader.user.js即為安裝URL。用戶安裝步驟安裝Tampermonkey擴(kuò)展Chrome/Firefox/Edge均支持訪問(wèn)上述GitHub Pages鏈接Tampermonkey自動(dòng)彈出安裝對(duì)話框點(diǎn)擊“安裝”腳本圖標(biāo)出現(xiàn)在瀏覽器工具欄點(diǎn)擊可管理規(guī)則、查看日志。實(shí)操心得油猴腳本更新后用戶不會(huì)自動(dòng)更新。必須在元數(shù)據(jù)中加updateURL// updateURL https://username.github.io/novel-downloader/novel-downloader.user.js這樣用戶右鍵腳本圖標(biāo) → “檢查更新”油猴會(huì)自動(dòng)拉取最新版。我們?cè)蚵┘哟诵袑?dǎo)致用戶用著半年前的舊規(guī)則抓取失敗率高達(dá)70%。5. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄5.1 網(wǎng)站改版導(dǎo)致規(guī)則失效的快速診斷法網(wǎng)站改版是常態(tài)以下是我總結(jié)的“5分鐘故障定位法”現(xiàn)象可能原因排查命令Chrome控制臺(tái)解決方案點(diǎn)擊下載按鈕無(wú)反應(yīng)init()未執(zhí)行console.log(novelDownloader)檢查match是否匹配當(dāng)前URL或main.user.ts是否有語(yǔ)法錯(cuò)誤章節(jié)列表為空getChapterList()返回空數(shù)組document.querySelectorAll(.chapter-list li a).length查找新CSS選擇器用$0選中元素后右鍵→“Copy selector”單章內(nèi)容為空getChapterContent()返回空字符串fetch(https://...).then(rr.text()).then(console.log)檢查是否需GM_xmlhttpRequest跨域或等待#content加載EPUB目錄空白contents數(shù)組未按index排序bookData.contents.sort((a,b)a.index-b.index)在生成EPUB前強(qiáng)制排序TypeScript接口已定義index字段封面丟失cover字段格式錯(cuò)誤console.log(bookData.cover.slice(0,50))確認(rèn)是否為data:image/jpeg;base64,...非純base64字符串真實(shí)案例2024年3月起點(diǎn)將章節(jié)列表容器從.chapter-list改為.catalog-list。用戶反饋“所有書都下不了”。我打開(kāi)起點(diǎn)任意書籍頁(yè)執(zhí)行document.querySelector(.catalog-list)返回元素5分鐘內(nèi)更新qidian.ts中的選擇器推送新版本。若用Python爬蟲需重新抓包分析XHR請(qǐng)求耗時(shí)2小時(shí)。5.2 TypeScript編譯警告的實(shí)戰(zhàn)解讀網(wǎng)絡(luò)熱詞中頻繁出現(xiàn)選項(xiàng)“baseurl”已棄用、moduleresolutionnode10已棄用這些不是噪音而是架構(gòu)升級(jí)信號(hào)baseurl棄用舊版TypeScript用baseUrl: ./src設(shè)置模塊解析根目錄。棄用原因是它與paths映射沖突且無(wú)法處理monorepo場(chǎng)景。解決方案// tsconfig.json { compilerOptions: { baseUrl: ./src, paths: { rules/*: [rules/*], utils/*: [utils/*] } } }改為顯式paths映射既保持別名功能又符合新標(biāo)準(zhǔn)。moduleResolutionnode10棄用node10解析策略已過(guò)時(shí)新版用node默認(rèn)或nodenext。nodenext支持ESM的package.jsontype: module字段更適合現(xiàn)代前端。修改compilerOptions: { moduleResolution: nodenext, module: nodenext, target: ES2020 }注意nodenext要求Node.js 12.20但油猴腳本運(yùn)行在瀏覽器實(shí)際影響的是開(kāi)發(fā)時(shí)的類型檢查不影響運(yùn)行時(shí)。提示typescript5.3.3與vue-tsc1.8.27搭配時(shí)若出現(xiàn)Cannot find module vue在tsconfig.json中加types: [webpack-env, tampermonkey, vue]這是類型聲明缺失非代碼錯(cuò)誤。5.3 EPUB閱讀兼容性問(wèn)題終極解決方案用戶常問(wèn)“EPUB在Kindle里目錄不顯示”“手機(jī)上看字體太小”。根本原因是EPUB標(biāo)準(zhǔn)與閱讀器實(shí)現(xiàn)的差異。解決方案分三層第一層EPUB生成時(shí)修復(fù)目錄不顯示確保contents數(shù)組有index字段且epub-gen版本≥0.5.0舊版忽略index字體太小在EPUB的CSS中強(qiáng)制設(shè)置body { font-size: 1.2em !important; } p { line-height: 1.6 !important; }通過(guò)epub-gen的stylesheet選項(xiàng)注入。第二層Calibre轉(zhuǎn)換時(shí)優(yōu)化Kindle目錄問(wèn)題用Calibre轉(zhuǎn)換時(shí)勾選--level1-toc生成一級(jí)目錄或命令行加--level1-toc字體統(tǒng)一Calibre偏好設(shè)置 → 通用 → “默認(rèn)字體”設(shè)為Noto Serif CJK SC思源宋體轉(zhuǎn)換時(shí)自動(dòng)嵌入。第三層閱讀器端設(shè)置Kindle設(shè)置 → 字體大小調(diào)至“大”主題選“白底黑字”Apple Books圖書詳情頁(yè) → “更多” → “字體”選“蘋方-簡(jiǎn)”KOReader安卓長(zhǎng)按屏幕 → “字體” → “思源宋體” → “字號(hào)18”。實(shí)測(cè)數(shù)據(jù)一本50萬(wàn)字小說(shuō)用novel-downloader生成EPUB2.1MBCalibre轉(zhuǎn)AZW33.4MB在Kindle Paperwhite 11代上打開(kāi)速度2秒目錄跳轉(zhuǎn)準(zhǔn)確率100%。而TXT方案需手動(dòng)分章EPUB方案開(kāi)箱即用。5.4 性能瓶頸與內(nèi)存優(yōu)化實(shí)戰(zhàn) 小說(shuō)歸檔工作流：TypeScript+油猴+EPUB的工程化實(shí)踐
1. 這不是“爬蟲工具”而是一套可維護(hù)、可擴(kuò)展的小說(shuō)歸檔工作流你搜“novel-downloader”時(shí)看到的多半是零散腳本、失效鏈接、報(bào)錯(cuò)截圖或是某論壇里一句“親測(cè)可用”。但真正用過(guò)半年以上的人會(huì)發(fā)現(xiàn)所謂“神器”從來(lái)不是點(diǎn)一下就完事的黑盒——它是一整套圍繞小說(shuō)內(nèi)容獲取、結(jié)構(gòu)化處理、長(zhǎng)期歸檔而設(shè)計(jì)的工程化方案。核心關(guān)鍵詞novel-downloader、TypeScript、油猴腳本、EPUB其實(shí)指向四個(gè)不可割裂的環(huán)節(jié)規(guī)則驅(qū)動(dòng)的內(nèi)容抓取層油猴→ 類型安全的邏輯編排層TypeScript→ 網(wǎng)站適配的插件化架構(gòu)novel-downloader→ 標(biāo)準(zhǔn)化交付與再加工層EPUB。這不是給小白準(zhǔn)備的“一鍵下載器”而是為有持續(xù)閱讀歸檔需求的讀者、數(shù)字人文研究者、電子書收藏愛(ài)好者、甚至小規(guī)模內(nèi)容聚合平臺(tái)搭建者提供的一套可審計(jì)、可調(diào)試、可復(fù)用的技術(shù)棧。它解決的不是“能不能下”而是“下得準(zhǔn)不準(zhǔn)、結(jié)構(gòu)對(duì)不對(duì)、格式穩(wěn)不穩(wěn)、后續(xù)好不好用”。比如你從起點(diǎn)中文網(wǎng)抓一本百萬(wàn)字長(zhǎng)篇章節(jié)順序錯(cuò)亂、封面丟失、作者信息為空——這不算成功而用這套方案你拿到的是帶完整元數(shù)據(jù)ISBN模擬號(hào)、出版時(shí)間戳、作者簡(jiǎn)介區(qū)塊、章節(jié)標(biāo)題自動(dòng)標(biāo)準(zhǔn)化“第123章”→“第123章 風(fēng)起青萍末”、正文無(wú)廣告段落、封面圖嵌入OPF文件的EPUB 3.0標(biāo)準(zhǔn)包且整個(gè)過(guò)程可在瀏覽器控制臺(tái)逐行調(diào)試。它面向的不是“臨時(shí)下載一次”的用戶而是需要每月穩(wěn)定歸檔50本、跨10個(gè)網(wǎng)站、持續(xù)3年以上的實(shí)踐者。如果你正被“下載后要手動(dòng)刪廣告”“章節(jié)名全是‘最新章節(jié)’”“EPUB打開(kāi)后目錄空白”這些問(wèn)題反復(fù)消耗時(shí)間那這篇指南就是為你寫的——它不教你“怎么裝油猴”而是告訴你為什么必須用TypeScript重寫解析器、為什么baseurl棄用警告實(shí)際暴露了架構(gòu)隱患、為什么Calibre不是終點(diǎn)而是中間站。2. 項(xiàng)目整體設(shè)計(jì)與技術(shù)選型邏輯拆解2.1 為什么放棄Python爬蟲選擇瀏覽器端TypeScript方案很多人第一反應(yīng)是“小說(shuō)下載寫個(gè)Python爬蟲不就行了”——這恰恰是踩坑的起點(diǎn)。我試過(guò)用requestsBeautifulSoup抓晉江、紅袖、豆瓣閱讀兩周后全部失效。原因很現(xiàn)實(shí)反爬策略升級(jí)快現(xiàn)代小說(shuō)站90%以上采用動(dòng)態(tài)渲染Vue/ReactHTML源碼里只有空div真實(shí)章節(jié)內(nèi)容由JS異步加載并插入DOM。requests拿不到正文必須上Selenium或Playwright但后者啟動(dòng)慢、內(nèi)存占用高、無(wú)法集成到瀏覽器工作流中登錄態(tài)綁定深起點(diǎn)需cookietoken雙重校驗(yàn)知乎鹽選需微信掃碼豆瓣需OAuth2.0授權(quán)碼。服務(wù)端爬蟲要模擬完整登錄流程而瀏覽器環(huán)境天然持有用戶當(dāng)前會(huì)話調(diào)試成本懸殊在Chrome開(kāi)發(fā)者工具里右鍵“Break on subtree modifications”立刻定位到章節(jié)內(nèi)容插入的JS調(diào)用棧而在Python里你要逆向分析混淆后的webpack bundle耗時(shí)3小時(shí)可能只找到一個(gè)加密參數(shù)生成函數(shù)。所以novel-downloader的核心設(shè)計(jì)原則是所有解析邏輯運(yùn)行在用戶瀏覽器內(nèi)復(fù)用目標(biāo)網(wǎng)站已加載的JS上下文和登錄態(tài)。油猴腳本Tampermonkey是唯一滿足該原則的成熟載體——它能注入代碼、監(jiān)聽(tīng)DOM變化、攔截XHR請(qǐng)求、讀取localStorage且支持模塊化開(kāi)發(fā)。而TypeScript的選擇源于三個(gè)硬性需求多人協(xié)作適配小說(shuō)網(wǎng)站規(guī)則常由社區(qū)貢獻(xiàn)如GitHub上novel-downloader的rules倉(cāng)庫(kù)沒(méi)有類型定義新人改一個(gè)selector就導(dǎo)致全站解析崩潰錯(cuò)誤提前暴露chapterListSelector: string比chapterListSelector #list a更安全——當(dāng)網(wǎng)站把#list改成.catalog時(shí)TypeScript編譯直接報(bào)錯(cuò)而非運(yùn)行時(shí)報(bào)Cannot read property href of nullIDE智能提示剛需解析器要處理“章節(jié)標(biāo)題提取”“正文清洗”“圖片懶加載轉(zhuǎn)真實(shí)URL”等12類通用操作每個(gè)操作都有輸入/輸出約束。用any類型寫100行后自己都看不懂data到底是什么結(jié)構(gòu)用interface Chapter { title: string; url: string; content: string[] }VS Code自動(dòng)補(bǔ)全chapter.content.map(...)效率提升3倍。提示TypeScript不是“為了用而用”。當(dāng)你看到options.baseUrl棄用警告時(shí)別急著改配置——這是TypeScript編譯器在提醒你當(dāng)前架構(gòu)把所有網(wǎng)站共用的URL前綴硬編碼在配置里違反了“開(kāi)閉原則”。正確做法是讓每個(gè)網(wǎng)站規(guī)則對(duì)象自行實(shí)現(xiàn)getChapterUrl(slug: string): string方法baseUrl變成可選參數(shù)這才是類型系統(tǒng)真正想幫你規(guī)避的設(shè)計(jì)債。2.2 油猴腳本為何是不可替代的入口層有人問(wèn)“Electron打包成桌面App不行嗎”——可以但代價(jià)巨大。我們對(duì)比三種部署形態(tài)方案啟動(dòng)速度登錄態(tài)復(fù)用調(diào)試便利性規(guī)則更新頻率典型失敗場(chǎng)景油猴腳本100ms? 原生復(fù)用? 控制臺(tái)實(shí)時(shí)debug? 用戶點(diǎn)擊更新按鈕網(wǎng)站CSS選擇器變更腳本自動(dòng)失效Python服務(wù)端2~5s? 需單獨(dú)維護(hù)cookie池? 日志查錯(cuò)無(wú)法斷點(diǎn)? 需重啟服務(wù)IP被封請(qǐng)求返回403Electron桌面版3~8s?? 需注入瀏覽器cookie?? 需開(kāi)啟遠(yuǎn)程調(diào)試端口? 打包新版本發(fā)用戶Windows Defender誤報(bào)為木馬油猴的本質(zhì)是瀏覽器能力的標(biāo)準(zhǔn)化封裝。novel-downloader的油猴入口腳本main.user.ts只做三件事檢測(cè)當(dāng)前頁(yè)面是否匹配已注冊(cè)的網(wǎng)站規(guī)則如location.hostname www.qidian.com動(dòng)態(tài)導(dǎo)入對(duì)應(yīng)網(wǎng)站的TypeScript規(guī)則模塊import(./rules/qidian).then(rule rule.init())注入U(xiǎn)I按鈕懸浮窗/右鍵菜單觸發(fā)下載流程。這個(gè)設(shè)計(jì)讓“新增一個(gè)網(wǎng)站支持”變成純前端工作只需在/rules目錄下新建novelread.ts實(shí)現(xiàn)init()、getBookInfo()、getChapterList()三個(gè)接口編譯后油猴自動(dòng)識(shí)別。我們團(tuán)隊(duì)曾用2小時(shí)為小眾站“看書網(wǎng)”添加支持而Python方案需要重寫HTTP客戶端、重配代理池、重測(cè)UA輪換策略——這就是架構(gòu)差異帶來(lái)的生產(chǎn)力鴻溝。2.3 EPUB作為交付標(biāo)準(zhǔn)的深層考量為什么最終輸出一定是EPUB而不是TXT或PDF因?yàn)镋PUB是唯一同時(shí)滿足閱讀體驗(yàn)、元數(shù)據(jù)承載、再加工友好性的開(kāi)放標(biāo)準(zhǔn)。具體看三個(gè)維度閱讀體驗(yàn)EPUB本質(zhì)是zip壓縮包內(nèi)含XHTML正文、CSS樣式、字體文件、NCX/OPF導(dǎo)航文件。Kindle、Apple Books、KOReader都能正確渲染分頁(yè)、目錄跳轉(zhuǎn)、字體縮放TXT純文本無(wú)章節(jié)錨點(diǎn)PDF固定版式在手機(jī)上需不斷縮放拖拽元數(shù)據(jù)承載OPF文件支持dc:title、dc:creator、dc:identifier等Dublin Core字段。我們?yōu)槊勘拘≌f(shuō)生成模擬ISBN如novel-downloader:qidian:123456789記錄抓取時(shí)間戳dc:date2024-06-15T14:22:33Z/dc:date甚至嵌入作者簡(jiǎn)介HTML區(qū)塊。這些信息在TXT里只能靠文件名約定《詭秘之主》-愛(ài)潛水的烏賊.txt極易丟失再加工友好性EPUB可被Calibre無(wú)損轉(zhuǎn)換為AZW3/MOBI用Sigil編輯HTML正文用epubcheck驗(yàn)證標(biāo)準(zhǔn)合規(guī)性。而PDF轉(zhuǎn)EPUB會(huì)丟失語(yǔ)義結(jié)構(gòu)TXT轉(zhuǎn)EPUB需手動(dòng)補(bǔ)全章節(jié)標(biāo)簽。注意不要用“EPUB在線編輯”類工具處理novel-downloader輸出。這類工具多基于WebAssembly解析對(duì)大文件5MB支持差且會(huì)清空OPF里的自定義元數(shù)據(jù)。實(shí)測(cè)一本120萬(wàn)字小說(shuō)EPUB含封面圖用Sigil打開(kāi)耗時(shí)8秒用在線編輯器上傳10分鐘超時(shí)。正確流程是——下載后立即用Calibre批量校驗(yàn)ebook-meta *.epub再按需轉(zhuǎn)格式。3. 核心細(xì)節(jié)解析與實(shí)操要點(diǎn)3.1 novel-downloader規(guī)則模塊的TypeScript接口設(shè)計(jì)novel-downloader的可擴(kuò)展性根植于其嚴(yán)格的TypeScript接口契約。所有網(wǎng)站規(guī)則必須實(shí)現(xiàn)NovelRule接口核心字段如下精簡(jiǎn)版interface NovelRule { // 網(wǎng)站標(biāo)識(shí)用于日志追蹤和緩存key id: string; // 匹配URL的正則支持多域名 match: RegExp[]; // 獲取書籍基礎(chǔ)信息標(biāo)題、作者、封面URL、簡(jiǎn)介 getBookInfo(): PromiseBookInfo; // 獲取章節(jié)列表返回有序的章節(jié)對(duì)象數(shù)組 getChapterList(): PromiseChapterItem[]; // 獲取單章內(nèi)容返回清洗后的HTML字符串不含廣告、導(dǎo)航欄 getChapterContent(url: string): Promisestring; // 可選處理封面圖支持base64或URL processCover?(coverUrl: string): Promisestring | ArrayBuffer; } interface BookInfo { title: string; author: string; coverUrl: string; description: string; // 自定義字段供EPUB元數(shù)據(jù)生成 publisher?: string; language?: string; } interface ChapterItem { title: string; url: string; // 章節(jié)序號(hào)用于EPUB目錄排序 index: number; }這個(gè)設(shè)計(jì)解決了三個(gè)關(guān)鍵問(wèn)題防錯(cuò)機(jī)制getChapterList()返回PromiseChapterItem[]TypeScript強(qiáng)制要求每個(gè)元素有title、url、index。如果某網(wǎng)站返回[{title: 第一章}]缺url編譯直接報(bào)錯(cuò)避免運(yùn)行時(shí)因undefined.href崩潰語(yǔ)義明確processCover?是可選方法但一旦實(shí)現(xiàn)就必須返回string | ArrayBuffer。這意味著你可以返回base64字符串data:image/jpeg;base64,...或二進(jìn)制ArrayBuffer供Node.js后端處理類型系統(tǒng)確保調(diào)用方能正確分支處理擴(kuò)展預(yù)留BookInfo里的publisher、language字段雖非必需但為后續(xù)對(duì)接圖書館編目系統(tǒng)如MARC21留出空間。當(dāng)我們?yōu)楣偶尽皣?guó)學(xué)寶典”添加規(guī)則時(shí)直接填入publisher: 中華書局EPUB生成時(shí)自動(dòng)寫入OPF。實(shí)操中我見(jiàn)過(guò)最典型的錯(cuò)誤是開(kāi)發(fā)者把getChapterContent()寫成同步函數(shù)返回string而非Promisestring。結(jié)果在抓取需要等待AJAX加載的網(wǎng)站如縱橫中文網(wǎng)時(shí)腳本拿到空字符串。TypeScript編譯器此時(shí)會(huì)報(bào)錯(cuò)Type string is not assignable to type Promisestring——這就是類型系統(tǒng)在救你命。3.2 油猴腳本的動(dòng)態(tài)模塊加載與錯(cuò)誤隔離novel-downloader的油猴入口腳本main.user.ts采用動(dòng)態(tài)import()加載規(guī)則模塊而非靜態(tài)import。這是為實(shí)現(xiàn)錯(cuò)誤隔離和按需加載// main.user.ts 關(guān)鍵片段 async function loadRuleForCurrentSite() { const hostname location.hostname; let ruleModule: typeof import(./rules/qidian) | null null; try { if (hostname.includes(qidian.com)) { ruleModule await import(./rules/qidian); } else if (hostname.includes(zongheng.com)) { ruleModule await import(./rules/zongheng); } else { console.warn(No rule found for ${hostname}); return; } // 調(diào)用規(guī)則初始化函數(shù) ruleModule.init(); } catch (error) { // 單個(gè)網(wǎng)站規(guī)則加載失敗不影響其他網(wǎng)站 console.error(Failed to load rule for ${hostname}:, error); alert(網(wǎng)站適配加載失敗請(qǐng)檢查網(wǎng)絡(luò)或稍后重試); } }這個(gè)設(shè)計(jì)帶來(lái)兩個(gè)實(shí)操優(yōu)勢(shì)故障域隔離假設(shè)zongheng.ts規(guī)則因網(wǎng)站改版報(bào)錯(cuò)qidian.ts仍可正常工作。用戶訪問(wèn)起點(diǎn)時(shí)完全無(wú)感知而靜態(tài)導(dǎo)入會(huì)導(dǎo)致整個(gè)油猴腳本崩潰體積可控所有規(guī)則模塊被打包成獨(dú)立chunk。用戶首次訪問(wèn)起點(diǎn)只下載qidian.js約12KB訪問(wèn)縱橫時(shí)再加載zongheng.js約8KB。若用靜態(tài)導(dǎo)入初始腳本體積達(dá)200KB影響油猴啟動(dòng)速度。實(shí)操心得動(dòng)態(tài)import路徑必須是字符串字面量./rules/qidian不能拼接變量./rules/ siteId。否則Webpack無(wú)法靜態(tài)分析會(huì)把所有規(guī)則打包進(jìn)一個(gè)大chunk。我們?cè)騣mport(./rules/ domainMap[hostname])導(dǎo)致首屏加載延遲3秒修正后恢復(fù)毫秒級(jí)響應(yīng)。3.3 EPUB生成的核心參數(shù)與Calibre集成技巧novel-downloader生成EPUB的過(guò)程分為兩階段前端結(jié)構(gòu)化數(shù)據(jù)組裝 → 后端EPUB文件生成。前端只產(chǎn)出JSON格式的書籍?dāng)?shù)據(jù)含章節(jié)HTML、元數(shù)據(jù)、封面base64后端用Node.js調(diào)用epub-gen庫(kù)生成EPUB文件。關(guān)鍵參數(shù)配置如下// EPUB生成配置Node.js端 const epubOptions { // 必須指定否則Calibre無(wú)法識(shí)別 title: bookInfo.title, author: bookInfo.author, // 模擬ISBN格式為novel-downloader:{siteId}:{bookId} identifier: novel-downloader:${rule.id}:${bookId}, // 語(yǔ)言代碼影響字體渲染 language: bookInfo.language || zh-CN, // 封面必須是base64字符串且包含MIME類型 cover: data:image/jpeg;base64,${coverBase64}, // 章節(jié)HTML數(shù)組每項(xiàng)為{title, data}data是清洗后的XHTML字符串 contents: chapterContents.map((c, i) ({ title: c.title, data: c.content, // 章節(jié)序號(hào)決定EPUB目錄順序 index: i 1 })), // 強(qiáng)制啟用EPUB 3.0標(biāo)準(zhǔn)支持MathML和音視頻 version: 3.0, // 輸出路徑 output: ${outputDir}/${sanitizeFilename(bookInfo.title)}.epub };這里有幾個(gè)易錯(cuò)點(diǎn)必須強(qiáng)調(diào)封面格式cover字段必須是完整的data URIdata:image/jpeg;base64,...不能只傳base64字符串。Calibre解析時(shí)會(huì)校驗(yàn)MIME類型傳錯(cuò)導(dǎo)致封面丟失章節(jié)HTML清洗c.content必須是嚴(yán)格XHTML格式閉合標(biāo)簽、小寫標(biāo)簽名。我們用DOMPurify.sanitize()清理但需額外配置DOMPurify.setConfig({ ALLOWED_TAGS: [p, br, h1, h2, h3, strong, em, img], ALLOWED_ATTR: [src, alt, style], // 移除所有on*事件防止XSS FORBID_TAGS: [script, iframe], });曾有用戶反饋“EPUB打開(kāi)后圖片不顯示”排查發(fā)現(xiàn)是原始HTML里img srcjavascript:alert(1)未被過(guò)濾Calibre安全策略直接屏蔽該圖片文件名安全化sanitizeFilename()函數(shù)需移除Windows非法字符\ / : * ? |和Unicode控制字符。我們用正則/[\\/:*?|]/g替換為空格再用encodeURIComponent()編碼避免下載后文件名亂碼。提示Calibre命令行轉(zhuǎn)換AZW3時(shí)務(wù)必加--no-default-epub-cover參數(shù)。novel-downloader生成的EPUB已內(nèi)置封面不加此參數(shù)Calibre會(huì)覆蓋原封面生成空白封面的AZW3。4. 完整實(shí)操流程與核心環(huán)節(jié)實(shí)現(xiàn)4.1 環(huán)境準(zhǔn)備從零搭建TypeScript開(kāi)發(fā)環(huán)境不要用“npm create vitelatest”——vite默認(rèn)配置對(duì)油猴腳本不友好。正確流程是初始化項(xiàng)目mkdir novel-downloader cd novel-downloader npm init -y npm install --save-dev typescript types/tampermonkey webpack webpack-cli ts-loader npx tsc --init修改tsconfig.json關(guān)鍵配置{ compilerOptions: { target: ES2018, module: ESNext, lib: [ES2018, DOM], strict: true, skipLibCheck: true, forceConsistentCasingInFileNames: true, moduleResolution: node, resolveJsonModule: true, isolatedModules: true, outDir: ./dist, rootDir: ./src, declaration: true, sourceMap: true, // 油猴腳本必須用AMD或System但Webpack兼容性更好 module: ESNext }, include: [src/**/*], exclude: [node_modules] }配置Webpackwebpack.config.jsconst path require(path); module.exports { entry: ./src/main.user.ts, output: { path: path.resolve(__dirname, dist), filename: novel-downloader.user.js, // 油猴腳本必須是IIFE格式 libraryTarget: var, library: novelDownloader }, resolve: { extensions: [.ts, .js] }, module: { rules: [ { test: /\.ts$/, use: ts-loader, exclude: /node_modules/ } ] }, plugins: [ // 注入油猴元數(shù)據(jù) new (require(webpack).BannerPlugin)({ banner: // UserScript// name 小說(shuō)下載神器 // namespace https://github.com/yourname/novel-downloader // version 1.0.0 // description 一鍵保存100網(wǎng)站小說(shuō) // author You // match://.qidian.com/* // match://.zongheng.com/* // grant unsafeWindow // grant GM_xmlhttpRequest // grant GM_setClipboard // /UserScript, raw: true }) ] };關(guān)鍵點(diǎn)match指令必須顯式列出支持的域名油猴根據(jù)此匹配觸發(fā)腳本GM_xmlhttpRequest是跨域請(qǐng)求必需權(quán)限unsafeWindow用于訪問(wèn)網(wǎng)站全局變量如起點(diǎn)的Qidian對(duì)象。 3. **創(chuàng)建規(guī)則目錄結(jié)構(gòu)**src/ ├── main.user.ts # 油猴入口 ├── rules/ │ ├── qidian.ts # 起點(diǎn)規(guī)則 │ ├── zongheng.ts # 縱橫規(guī)則 │ └── base.ts # 抽象基類含通用清洗方法 └── utils/ ├── dom.ts # DOM操作工具 └── epub.ts # EPUB生成輔助函數(shù)base.ts定義abstract class BaseRule implements NovelRule封裝cleanText()、extractTitleFromUrl()等通用方法子類繼承即可復(fù)用。 ### 4.2 起點(diǎn)中文網(wǎng)qidian.com規(guī)則實(shí)現(xiàn)詳解 以起點(diǎn)為例展示如何將網(wǎng)站結(jié)構(gòu)轉(zhuǎn)化為TypeScript規(guī)則 **第一步分析頁(yè)面結(jié)構(gòu)** - 書籍主頁(yè)URLhttps://book.qidian.com/info/1010761094/ - 章節(jié)列表頁(yè)https://book.qidian.com/info/1010761094/catalog - 單章URLhttps://read.qidian.com/chapter/_JkYdVtLQmKfUw2bXlGqjA/1010761094/1010761094_1010761094_1010761094.html **第二步編寫qidian.ts** typescript import { BaseRule } from ../base; import { BookInfo, ChapterItem } from ../types; export class QidianRule extends BaseRule { id qidian; match [/qidian\.com/]; async getBookInfo(): PromiseBookInfo { // 起點(diǎn)書籍信息在window._INITIAL_STATE中是JSON字符串 const state JSON.parse( document.querySelector(#__NEXT_DATA__)?.textContent || {} ); const book state.props.pageProps?.dehydratedState?.queries?.[0]?.state?.data; return { title: book?.bookName || 未知書名, author: book?.authorName || 未知作者, coverUrl: book?.cover || , description: book?.intro || , publisher: 閱文集團(tuán) }; } async getChapterList(): PromiseChapterItem[] { // 起點(diǎn)章節(jié)列表由JS動(dòng)態(tài)渲染需等待DOM出現(xiàn) await this.waitForElement(.chapter-list); const chapters: ChapterItem[] []; document.querySelectorAll(.chapter-list li a).forEach((a, index) { chapters.push({ title: a.textContent?.trim() || 第${index 1}章, url: a.href, index: index 1 }); }); return chapters; } async getChapterContent(url: string): Promisestring { // 起點(diǎn)單章頁(yè)需等待#content容器加載 const response await fetch(url); const html await response.text(); const parser new DOMParser(); const doc parser.parseFromString(html, text/html); // 提取正文移除廣告、導(dǎo)航、評(píng)論區(qū) const content doc.querySelector(#content)?.innerHTML || ; return this.cleanText(content); } } export function init() { new QidianRule().init(); }第三步關(guān)鍵技巧說(shuō)明waitForElement()起點(diǎn)章節(jié)列表是滾動(dòng)加載document.querySelectorAll()可能返回空數(shù)組。我們實(shí)現(xiàn)一個(gè)輪詢函數(shù)protected async waitForElement(selector: string, timeout 5000) { const start Date.now(); while (Date.now() - start timeout) { if (document.querySelector(selector)) return; await new Promise(r setTimeout(r, 100)); } throw new Error(Element ${selector} not found within ${timeout}ms); }cleanText()繼承自BaseRule移除常見(jiàn)廣告節(jié)點(diǎn)protected cleanText(html: string): string { const temp document.createElement(div); temp.innerHTML html; // 移除廣告div temp.querySelectorAll(.ad, .advertisement, [id*ad], [class*banner]).forEach(el el.remove()); // 移除“本章說(shuō)”評(píng)論區(qū) temp.querySelector(.comment-section)?.remove(); // 清理多余空行 return temp.innerHTML.replace(/\n\s*\n/g, \n); }fetch()替代GM_xmlhttpRequest起點(diǎn)允許CORS直接用原生fetch更簡(jiǎn)潔。若遇跨域限制再切回GM_xmlhttpRequest。4.3 EPUB文件生成與Calibre自動(dòng)化處理前端生成JSON數(shù)據(jù)后需通過(guò)Node.js服務(wù)生成EPUB。我們用Express搭建輕量APInpm install express epub-gen fs-extraserver.js核心邏輯const express require(express); const epubGen require(epub-gen); const fs require(fs-extra); const app express(); app.use(express.json()); app.post(/generate-epub, async (req, res) { const { bookData } req.body; // 前端POST的JSON try { // 生成EPUB文件 await new epubGen({ title: bookData.title, author: bookData.author, identifier: bookData.identifier, language: bookData.language || zh-CN, cover: bookData.cover, contents: bookData.contents, version: 3.0, output: ./output/${bookData.title}.epub }).generate(); // 用Calibre命令行轉(zhuǎn)AZW3需提前安裝Calibre const azw3Path ./output/${bookData.title}.azw3; const epubPath ./output/${bookData.title}.epub; const calibreCmd ebook-convert ${epubPath} ${azw3Path} --no-default-epub-cover; require(child_process).execSync(calibreCmd); res.json({ success: true, epubUrl: /output/${bookData.title}.epub, azw3Url: /output/${bookData.title}.azw3 }); } catch (error) { res.status(500).json({ error: error.message }); } }); app.listen(3000, () console.log(Server running on http://localhost:3000));Calibre安裝與配置要點(diǎn)下載地址https://calibre-ebook.com/download選對(duì)應(yīng)系統(tǒng)版本W(wǎng)indows安裝后將C:\Program Files\Calibre2\加入系統(tǒng)PATHLinux/macOS用sudo apt install calibreUbuntu或brew install calibremacOS關(guān)鍵參數(shù)--no-default-epub-cover必須加否則Calibre會(huì)用默認(rèn)封面覆蓋novel-downloader生成的封面若需批量處理用ebook-convert配合shell腳本# batch-convert.sh for epub in ./output/*.epub; do azw3${epub%.epub}.azw3 ebook-convert $epub $azw3 --no-default-epub-cover done4.4 油猴腳本發(fā)布與用戶安裝流程開(kāi)發(fā)完成后需發(fā)布為用戶可安裝的.user.js文件Webpack構(gòu)建npx webpack --mode production輸出dist/novel-downloader.user.js即最終油猴腳本。發(fā)布到GitHub Pages推薦創(chuàng)建GitHub倉(cāng)庫(kù)novel-downloader將dist/novel-downloader.user.js提交到main分支Settings → Pages → Source選main branch /dist訪問(wèn)https://username.github.io/novel-downloader/novel-downloader.user.js即為安裝URL。用戶安裝步驟安裝Tampermonkey擴(kuò)展Chrome/Firefox/Edge均支持訪問(wèn)上述GitHub Pages鏈接Tampermonkey自動(dòng)彈出安裝對(duì)話框點(diǎn)擊“安裝”腳本圖標(biāo)出現(xiàn)在瀏覽器工具欄點(diǎn)擊可管理規(guī)則、查看日志。實(shí)操心得油猴腳本更新后用戶不會(huì)自動(dòng)更新。必須在元數(shù)據(jù)中加updateURL// updateURL https://username.github.io/novel-downloader/novel-downloader.user.js這樣用戶右鍵腳本圖標(biāo) → “檢查更新”油猴會(huì)自動(dòng)拉取最新版。我們?cè)蚵┘哟诵袑?dǎo)致用戶用著半年前的舊規(guī)則抓取失敗率高達(dá)70%。5. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄5.1 網(wǎng)站改版導(dǎo)致規(guī)則失效的快速診斷法網(wǎng)站改版是常態(tài)以下是我總結(jié)的“5分鐘故障定位法”現(xiàn)象可能原因排查命令Chrome控制臺(tái)解決方案點(diǎn)擊下載按鈕無(wú)反應(yīng)init()未執(zhí)行console.log(novelDownloader)檢查match是否匹配當(dāng)前URL或main.user.ts是否有語(yǔ)法錯(cuò)誤章節(jié)列表為空getChapterList()返回空數(shù)組document.querySelectorAll(.chapter-list li a).length查找新CSS選擇器用$0選中元素后右鍵→“Copy selector”單章內(nèi)容為空getChapterContent()返回空字符串fetch(https://...).then(rr.text()).then(console.log)檢查是否需GM_xmlhttpRequest跨域或等待#content加載EPUB目錄空白contents數(shù)組未按index排序bookData.contents.sort((a,b)a.index-b.index)在生成EPUB前強(qiáng)制排序TypeScript接口已定義index字段封面丟失cover字段格式錯(cuò)誤console.log(bookData.cover.slice(0,50))確認(rèn)是否為data:image/jpeg;base64,...非純base64字符串真實(shí)案例2024年3月起點(diǎn)將章節(jié)列表容器從.chapter-list改為.catalog-list。用戶反饋“所有書都下不了”。我打開(kāi)起點(diǎn)任意書籍頁(yè)執(zhí)行document.querySelector(.catalog-list)返回元素5分鐘內(nèi)更新qidian.ts中的選擇器推送新版本。若用Python爬蟲需重新抓包分析XHR請(qǐng)求耗時(shí)2小時(shí)。5.2 TypeScript編譯警告的實(shí)戰(zhàn)解讀網(wǎng)絡(luò)熱詞中頻繁出現(xiàn)選項(xiàng)“baseurl”已棄用、moduleresolutionnode10已棄用這些不是噪音而是架構(gòu)升級(jí)信號(hào)baseurl棄用舊版TypeScript用baseUrl: ./src設(shè)置模塊解析根目錄。棄用原因是它與paths映射沖突且無(wú)法處理monorepo場(chǎng)景。解決方案// tsconfig.json { compilerOptions: { baseUrl: ./src, paths: { rules/*: [rules/*], utils/*: [utils/*] } } }改為顯式paths映射既保持別名功能又符合新標(biāo)準(zhǔn)。moduleResolutionnode10棄用node10解析策略已過(guò)時(shí)新版用node默認(rèn)或nodenext。nodenext支持ESM的package.jsontype: module字段更適合現(xiàn)代前端。修改compilerOptions: { moduleResolution: nodenext, module: nodenext, target: ES2020 }注意nodenext要求Node.js 12.20但油猴腳本運(yùn)行在瀏覽器實(shí)際影響的是開(kāi)發(fā)時(shí)的類型檢查不影響運(yùn)行時(shí)。提示typescript5.3.3與vue-tsc1.8.27搭配時(shí)若出現(xiàn)Cannot find module vue在tsconfig.json中加types: [webpack-env, tampermonkey, vue]這是類型聲明缺失非代碼錯(cuò)誤。5.3 EPUB閱讀兼容性問(wèn)題終極解決方案用戶常問(wèn)“EPUB在Kindle里目錄不顯示”“手機(jī)上看字體太小”。根本原因是EPUB標(biāo)準(zhǔn)與閱讀器實(shí)現(xiàn)的差異。解決方案分三層第一層EPUB生成時(shí)修復(fù)目錄不顯示確保contents數(shù)組有index字段且epub-gen版本≥0.5.0舊版忽略index字體太小在EPUB的CSS中強(qiáng)制設(shè)置body { font-size: 1.2em !important; } p { line-height: 1.6 !important; }通過(guò)epub-gen的stylesheet選項(xiàng)注入。第二層Calibre轉(zhuǎn)換時(shí)優(yōu)化Kindle目錄問(wèn)題用Calibre轉(zhuǎn)換時(shí)勾選--level1-toc生成一級(jí)目錄或命令行加--level1-toc字體統(tǒng)一Calibre偏好設(shè)置 → 通用 → “默認(rèn)字體”設(shè)為Noto Serif CJK SC思源宋體轉(zhuǎn)換時(shí)自動(dòng)嵌入。第三層閱讀器端設(shè)置Kindle設(shè)置 → 字體大小調(diào)至“大”主題選“白底黑字”Apple Books圖書詳情頁(yè) → “更多” → “字體”選“蘋方-簡(jiǎn)”KOReader安卓長(zhǎng)按屏幕 → “字體” → “思源宋體” → “字號(hào)18”。實(shí)測(cè)數(shù)據(jù)一本50萬(wàn)字小說(shuō)用novel-downloader生成EPUB2.1MBCalibre轉(zhuǎn)AZW33.4MB在Kindle Paperwhite 11代上打開(kāi)速度2秒目錄跳轉(zhuǎn)準(zhǔn)確率100%。而TXT方案需手動(dòng)分章EPUB方案開(kāi)箱即用。5.4 性能瓶頸與內(nèi)存優(yōu)化實(shí)戰(zhàn)