1. 為什么現(xiàn)在還要重新啃 Manifest.jsonMV3 的一場(chǎng)強(qiáng)制遷徙2023 年初開(kāi)始Chrome Web Store 就關(guān)閉了 Manifest V2 插件的新提交通道到 2024 年更是全面停止了對(duì) MV2 擴(kuò)展的支持。這意味著什么如果你手上還有一套用browser_action、background.scripts寫(xiě)的老插件哪怕它運(yùn)行得好好的也會(huì)在用戶(hù)瀏覽器里被強(qiáng)制禁用取而代之的是一個(gè)灰色圖標(biāo)加上已停用的提示。很多開(kāi)發(fā)者就是在這個(gè)節(jié)點(diǎn)上被迫開(kāi)始讀 Manifest.json 文檔的我也不例外。當(dāng)時(shí)我手上有三個(gè)線上插件要遷移翻遍官方文檔和各類(lèi)碎片文章發(fā)現(xiàn)了一個(gè)尷尬的事實(shí)Manifest V3 的字段說(shuō)明散落在不同頁(yè)面很少有文章能從頭到尾把所有字段講清楚更沒(méi)有幾篇能告訴你這個(gè)字段在 MV3 里已經(jīng)改了、那個(gè)字段千萬(wàn)別照舊填。如果你正準(zhǔn)備開(kāi)發(fā)一個(gè)新的 Chrome 插件或者正在為老插件做遷移那么 Manifest.json 就是你繞不開(kāi)的第一道門(mén)。它不只是一個(gè)聲明文件它決定了你的插件能拿到什么權(quán)限、能跑哪些代碼、能在什么頁(yè)面里注入腳本、UI 長(zhǎng)什么樣。我在做遷移的過(guò)程中因?yàn)樽侄卫斫馄畈攘瞬簧倏佑行┛釉诠俜轿臋n里壓根不會(huì)寫(xiě)。這篇文章我就按照自己實(shí)際操作過(guò)的順序把 MV3 版本 Manifest.json 的字段從頭到尾拆一遍重點(diǎn)標(biāo)注那些和 MV2 差異巨大、特別容易翻車(chē)的地方。文章適合三種人第一次寫(xiě)插件的新手、從 MV2 遷移的老手、以及想在發(fā)布前自查一遍配置細(xì)節(jié)的開(kāi)發(fā)者。在進(jìn)入逐字段分析之前先想明白一件事MV3 的整體設(shè)計(jì)思路說(shuō)白了就是收緊權(quán)限、消滅常駐后臺(tái)、禁止遠(yuǎn)程代碼。這三個(gè)原則幾乎解釋了 Manifest.json 里所有字段的增刪改變化。你只有把這三個(gè)原則刻在腦子里再看字段列表時(shí)就不會(huì)覺(jué)得有些限制莫名其妙了。2. 三個(gè)看不見(jiàn)但決定一切的 MV3 設(shè)計(jì)原則2.1 常駐后臺(tái)頁(yè)被砍掉一切邏輯交給 Service WorkerMV2 時(shí)代我們習(xí)慣在后臺(tái)配置一個(gè)background.html里面掛一個(gè)長(zhǎng)期運(yùn)行的 JavaScript 環(huán)境用來(lái)監(jiān)聽(tīng)事件、維護(hù)狀態(tài)、處理消息。這個(gè)頁(yè)面只要瀏覽器開(kāi)著就會(huì)運(yùn)行哪怕什么都不做也在消耗內(nèi)存。MV3 直接把這種模式廢了換成了 Service Worker——一種用完即走的腳本環(huán)境插件被觸發(fā)時(shí)才啟動(dòng)、空閑一段時(shí)間后自動(dòng)休眠下次再被事件喚醒時(shí)重新執(zhí)行。這個(gè)設(shè)計(jì)對(duì) Manifest.json 最直接的影響就是background字段的寫(xiě)法完全不同了。MV2 里常見(jiàn)的是background: {scripts: [bg.js], persistent: true}到了 MV3 變成background: {service_worker: bg.js}。別小看這個(gè)變化persistent字段整個(gè)消失了因?yàn)?MV3 里不存在持久后臺(tái)的概念而且service_worker只能指定一個(gè)文件不能再像 MV2 那樣寫(xiě)一個(gè)數(shù)組。如果你想按模塊拆分代碼需要在background.service_worker.type里設(shè)置為module用 ES Module 的方式來(lái)組織代碼。我剛遷移時(shí)在這個(gè)坑里卡了兩天我把老代碼拆成了background.js和utils.js兩個(gè)文件按照 MV2 的慣性把它們寫(xiě)進(jìn)數(shù)組結(jié)果 MV3 直接報(bào)錯(cuò)Service worker cannot be an array改成只保留一個(gè)入口文件后又發(fā)現(xiàn)我在background.js里用import導(dǎo)入utils.js的函數(shù)報(bào)錯(cuò)說(shuō)import語(yǔ)句只能用在外層 module 環(huán)境。最后才發(fā)現(xiàn)要加type: module。這一個(gè)小字段官方文檔里放在不起眼的角落但不知道它的話ES Module 寫(xiě)法就是跑不通。2.2 權(quán)限邊界大幅收窄h(huán)ost_permissions 被單獨(dú)拎出來(lái)MV2 里所有權(quán)限都堆在一個(gè)permissions數(shù)組里包括tabs、storage、http://*/這類(lèi)站點(diǎn)權(quán)限。MV3 把訪問(wèn)哪些網(wǎng)站這種高危權(quán)限單獨(dú)拆成了一個(gè)字段host_permissions和permissions分開(kāi)放置。邏輯很清楚permissions管的是 Chrome 提供的 API 能力比如storage存儲(chǔ)、alarms定時(shí)器、clipboardRead讀剪貼板而host_permissions管的是你的腳本能跑在哪些域名上比如https://*.example.com/*。為什么要這么拆因?yàn)樵?Chrome 的權(quán)限提示 UI 里用戶(hù)可以清楚地看到這個(gè)插件能讀取你在所有網(wǎng)站上的數(shù)據(jù)而不會(huì)把它和插件能使用存儲(chǔ) API混為一談。如果你只聲明了host_permissions而沒(méi)有在permissions里聲明對(duì)應(yīng) API那么你能往頁(yè)面上注入腳本但未必能調(diào)用chrome.storage反過(guò)來(lái)你聲明了storageAPI 權(quán)限但沒(méi)聲明任何host_permissions你的腳本就哪兒也去不了。這兩個(gè)字段是配合關(guān)系不是替代關(guān)系。我在給一個(gè)網(wǎng)頁(yè)標(biāo)注工具做遷移時(shí)把permissions: [activeTab, scripting, storage, https://*/*]直接復(fù)制到了 MV3Chrome 倒是沒(méi)報(bào)錯(cuò)但審核時(shí)被拒了理由是權(quán)限申請(qǐng)范圍過(guò)大。后來(lái)我改成permissions: [activeTab, scripting, storage]加上host_permissions: [https://*/*]的組合。這里有個(gè)隱藏邏輯如果只用activeTab其實(shí)可以完全不用host_permissions因?yàn)檫@個(gè)權(quán)限會(huì)讓你在用戶(hù)主動(dòng)點(diǎn)擊插件圖標(biāo)時(shí)獲得當(dāng)前標(biāo)簽頁(yè)的一次性訪問(wèn)權(quán)。能少聲明就少聲明審核更容易通過(guò)用戶(hù)安裝時(shí)的安全感也更強(qiáng)。2.3 遠(yuǎn)程代碼全面禁止CSP 規(guī)則從字符串變成對(duì)象MV2 時(shí)代在content_security_policy里你可以寫(xiě)script-src self https://some-cdn.com;然后直接在插件頁(yè)面里引入遠(yuǎn)程 CDN 的腳本。MV3 一刀切了推廣線上 CSP 只允許self不允許任何遠(yuǎn)程源、不允許eval、不允許wasm-eval。這意味著你的插件代碼、依賴(lài)庫(kù)、所有邏輯都必須打包進(jìn)插件本地的文件里想在運(yùn)行時(shí)從服務(wù)器拉腳本沒(méi)門(mén)。對(duì)應(yīng)到 Manifest.json 里MV3 的content_security_policy字段變成了一種對(duì)象結(jié)構(gòu)包含extension_pages和sandbox兩個(gè)屬性。extension_pages管的是插件自帶的頁(yè)面比如彈窗頁(yè)、設(shè)置頁(yè)、獨(dú)立標(biāo)簽頁(yè)這個(gè)值基本只能設(shè)為script-src self; object-src self;幾乎沒(méi)有操作空間sandbox才是留給你自由發(fā)揮的空間如果你需要做一些不安全的操作比如通過(guò)eval執(zhí)行動(dòng)態(tài)代碼可以讓這些代碼在沙盒頁(yè)面里跑。我之前寫(xiě)過(guò)一個(gè)小工具需要在彈窗頁(yè)里動(dòng)態(tài)拼一段模板字符串然后執(zhí)行MV2 里靠eval就解決了。遷到 MV3 后發(fā)現(xiàn)整個(gè)彈窗頁(yè)控制臺(tái)全是 CSP 報(bào)錯(cuò)代碼一行都跑不了。最后只能把動(dòng)態(tài)執(zhí)行的部分單獨(dú)拆到一個(gè)沙盒 iframe 頁(yè)面里然后在主頁(yè)面和 iframe 之間用postMessage通信。這個(gè)改動(dòng)上線后反而更穩(wěn)定了因?yàn)樯澈许?yè)面里的錯(cuò)誤不會(huì)影響主頁(yè)面。如果你習(xí)慣了在插件里從遠(yuǎn)程服務(wù)器拉取最新腳本做熱更新MV3 下這個(gè)方案基本是死路必須改為發(fā)版更新。3. 基礎(chǔ)信息字段逐個(gè)拆name、version、icons 里的小監(jiān)獄3.1 manifest_version、name、version格式不對(duì)連加載都失敗先說(shuō)最基礎(chǔ)但最容易被忽略的。manifest_version在 MV3 下必須寫(xiě)整數(shù)3而且必須是數(shù)字類(lèi)型不能寫(xiě)字符串3。這是 Chrome 在解析時(shí)直接強(qiáng)校驗(yàn)的寫(xiě)錯(cuò)的話插件在chrome://extensions頁(yè)面會(huì)顯示無(wú)法加載清單文件。name字段限制是 45 個(gè)字符description限制是 132 個(gè)字符。這兩個(gè)都算好說(shuō)真正坑人的是version。MV3 要求版本號(hào)最多 4 段數(shù)字每段只能是 1 到 2 位數(shù)字也就是說(shuō)1.0、1.0.2、1.2.3.4都合法但1.0.0.0.0不合法1.10合法因?yàn)?0是兩位數(shù)1.100就出問(wèn)題了——等等每段允許 1 到 2 位數(shù)字所以1.100不合法。很多開(kāi)發(fā)者在這里翻車(chē)是因?yàn)樗麄冇萌掌诋?dāng)版本號(hào)比如2024.12.31看起來(lái)沒(méi)問(wèn)題但如果月份或日期變成三位數(shù)呢而且 Chrome Web Store 的版本號(hào)必須是遞增的你傳了一個(gè)比線上更低的版本號(hào)上去直接給你拒回來(lái)。我自己的做法是維護(hù)一個(gè)簡(jiǎn)單的遞增規(guī)則主版本號(hào).功能版本號(hào).修復(fù)版本號(hào)比如2.4.1。每次提交前先在本地跑一遍chrome --pack-extension打包驗(yàn)證確保版本號(hào)能被解析。如果你用自動(dòng)化發(fā)布腳本記得在腳本里加一個(gè)版本號(hào)遞增的檢查邏輯不然 CI 里很容易因?yàn)槭只寻姹咎?hào)填低了導(dǎo)致發(fā)布失敗。3.2 default_locale、key、icons平時(shí)不起眼缺了就出亂子default_locale這個(gè)字段是在你要做國(guó)際化i18n時(shí)才需要的。一旦你設(shè)置了它就必須在插件根目錄下建一個(gè)_locales文件夾里面至少有一個(gè)和default_locale值對(duì)應(yīng)的語(yǔ)言文件。比如default_locale: zh_CN時(shí)_locales/zh_CN/messages.json必須存在否則插件加載直接報(bào)錯(cuò)。這個(gè)字段的設(shè)計(jì)初衷是告訴 Chrome 你的默認(rèn)語(yǔ)言是什么然后 Chrome 會(huì)優(yōu)先加載用戶(hù)瀏覽器語(yǔ)言對(duì)應(yīng)的 messages 文件找不到再回退到默認(rèn)語(yǔ)言。key字段可能是所有字段里最容易被誤解的一個(gè)。它不是你在 Manifest.json 里手寫(xiě)的而是 Chrome 在你打包插件時(shí)生成的。它的作用是固定插件的 ID這樣無(wú)論用戶(hù)從商店安裝還是你用--load-extension本地加載插件 ID 都是一樣的。這對(duì)依賴(lài)固定 ID 的開(kāi)發(fā)場(chǎng)景特別重要比如你通過(guò)externally_connectable讓別的擴(kuò)展和自己通信時(shí)ID 變了就全斷了。如果你在開(kāi)發(fā)環(huán)境里發(fā)現(xiàn)插件 ID 每次刷新都不一樣那大概率是沒(méi)設(shè)置key字段。怎么拿 key先在瀏覽器里加載一次未打包的擴(kuò)展然后在chrome://extensions頁(yè)面開(kāi)啟開(kāi)發(fā)者模式查看擴(kuò)展詳情復(fù)制它的 ID再到擴(kuò)展目錄里用工具生成對(duì)應(yīng) Base64 的 key填進(jìn) manifest 后重新加載就能固定 ID 了。icons字段聲明 16、32、48、128 四種尺寸的圖標(biāo)很多新手會(huì)把四個(gè)尺寸都設(shè)置成同一張圖片這其實(shí)不太對(duì)。16 和 32 是頂欄工具欄用的圖標(biāo)太小的話會(huì)糊48 是擴(kuò)展管理頁(yè)大圖標(biāo)128 是商店列表頁(yè)圖標(biāo)。最省事的方案是準(zhǔn)備一張 128x128 的源圖然后用工具導(dǎo)出四個(gè)尺寸。注意icons里的路徑是相對(duì) Manifest.json 所在目錄的不要用../這種寫(xiě)法會(huì)解析失敗。4. 核心功能字段全面拆解從 background 到 content_scripts 到 action4.1 background.service_worker注冊(cè)規(guī)則與生命周期控制在 MV3 里background字段最常見(jiàn)的寫(xiě)法是這樣background: { service_worker: service-worker.js, type: module }service_worker的值是相對(duì)于插件根目錄的路徑。type設(shè)為module時(shí)這個(gè) worker 會(huì)以 ES Module 的身份執(zhí)行你可以在里面用import語(yǔ)句引入其他模塊這是目前最推薦的寫(xiě)法。但注意MV3 的 Service Worker 有幾個(gè)和普通頁(yè)面腳本完全不同的特性理解它們才能正確配置字段它是事件驅(qū)動(dòng)的空閑約 30 秒就會(huì)被終止。所以你不能在 worker 里掛一個(gè)全局變量長(zhǎng)期保存狀態(tài)狀態(tài)要存到chrome.storage或 IndexedDB。監(jiān)聽(tīng)器必須在頂層同步注冊(cè)。如果你在chrome.runtime.onInstalled.addListener的回調(diào)里再注冊(cè)其他事件的監(jiān)聽(tīng)worker 休眠后這些監(jiān)聽(tīng)器可能丟失。在 worker 里訪問(wèn) DOM 是不行的document、window這些對(duì)象都不存在。我早期犯過(guò)一個(gè)錯(cuò)我在 worker 里用了setInterval定時(shí)去輪詢(xún)接口想著這跟 MV2 的后臺(tái)頁(yè)一樣會(huì)一直跑。結(jié)果每次休眠喚醒后定時(shí)器就斷了甚至接口請(qǐng)求都會(huì)因?yàn)?CORS 問(wèn)題失敗。后來(lái)我把定時(shí)任務(wù)改成使用chrome.alarmsAPI配合chrome.storage存儲(chǔ)上一次的輪詢(xún)時(shí)間戳才做到了永久任務(wù)。如果你原本在 MV2 里用setInterval做了很多周期任務(wù)遷移到 MV3 時(shí)務(wù)必要全部改成chrome.alarms。4.2 content_scripts注入時(shí)機(jī)與匹配規(guī)則的細(xì)節(jié)content_scripts字段在 MV2 和 MV3 里形式差不多但有幾個(gè)細(xì)節(jié)需要注意。一個(gè)典型的配置content_scripts: [ { matches: [https://*.example.com/*], js: [content.js], css: [content.css], run_at: document_idle, all_frames: false, world: ISOLATED } ]matches是匹配規(guī)則寫(xiě)法是 Chrome 匹配模式match pattern比如https://*/*、http://localhost/*、all_urls。注意不要在matches里出現(xiàn)http://localhost:8080/*這種帶端口的寫(xiě)法端口在匹配模式里是不支持的如果你要匹配本地開(kāi)發(fā)地址得寫(xiě)成http://localhost/*然后靠include_globs或 JS 里自行判斷端口。run_at有三個(gè)可選值document_startDOM 剛開(kāi)始構(gòu)建、document_endDOM 解析完、document_idle頁(yè)面加載完默認(rèn)值。如果你要在頁(yè)面加載早期攔截某些請(qǐng)求就需要document_start如果只是往頁(yè)面上加個(gè)按鈕document_idle足夠。這個(gè)字段直接影響腳本的執(zhí)行時(shí)機(jī)改錯(cuò)了會(huì)導(dǎo)致找不到 DOM 元素。world是 MV3 新增的字段取值為ISOLATED默認(rèn)或MAIN。ISOLATED表示腳本運(yùn)行在獨(dú)立的 JavaScript 環(huán)境中和頁(yè)面本身的 JS 環(huán)境隔離——頁(yè)面里的全局變量你訪問(wèn)不到你定義的變量也不會(huì)污染頁(yè)面MAIN則表示腳本注入到頁(yè)面自己的世界可以和頁(yè)面腳本共享 DOM 和全局變量。需要注意的是MAIN模式下你的腳本等于和頁(yè)面里其他腳本平起平坐頁(yè)面腳本可能會(huì)惡意修改你的方法所以除非真需要操作頁(yè)面自己的全局函數(shù)否則保持默認(rèn)ISOLATED就好。4.3 action 與 commands工具欄按鈕、彈窗和快捷鍵MV2 里的browser_action和page_action在 MV3 被統(tǒng)一成了action。因?yàn)楹芏嗖寮鋵?shí)不需要區(qū)分工具欄按鈕一直可見(jiàn)和只在特定頁(yè)面可見(jiàn)Chrome 干脆合并了統(tǒng)一默認(rèn)可見(jiàn)然后用程序控制在特定頁(yè)面禁用按鈕。Manifest.json 里action字段的典型寫(xiě)法action: { default_popup: popup.html, default_title: 點(diǎn)擊打開(kāi)面板, default_icon: { 16: icons/icon16.png, 32: icons/icon32.png } }default_popup指定點(diǎn)擊按鈕后彈出的 HTML 頁(yè)面路徑這個(gè)頁(yè)面有自己的獨(dú)立窗口寬高受限最高 800x600。如果你不想用彈窗而是想在點(diǎn)擊按鈕后通過(guò)chrome.scripting.executeScript執(zhí)行一段腳本那就不需要default_popup只需要在background里監(jiān)聽(tīng)chrome.action.onClicked事件。注意一個(gè)坑一旦設(shè)置了default_popupchrome.action.onClicked事件就不會(huì)觸發(fā)了。有時(shí)我在調(diào)試時(shí)發(fā)現(xiàn)點(diǎn)擊按鈕沒(méi)反應(yīng)第一反應(yīng)是去看 onClicked 監(jiān)聽(tīng)器結(jié)果發(fā)現(xiàn)是上次忘了刪default_popup。兩個(gè)機(jī)制是互斥的只能選一個(gè)。commands字段用來(lái)聲明快捷鍵它不屬于action但經(jīng)常配合action使用。例如commands: { toggle-feature: { suggested_key: { default: CtrlShiftY, mac: CommandShiftY }, description: 開(kāi)關(guān)某項(xiàng)功能 } }當(dāng)你在 manifest 里聲明了commands需要在一個(gè)頁(yè)面里調(diào)用chrome.commands.onCommand.addListener來(lái)監(jiān)聽(tīng)觸發(fā)并執(zhí)行對(duì)邏輯。系統(tǒng)快捷鍵有保留鍵位比如 CtrlShift某些特殊鍵如果沖突Chrome 會(huì)在chrome://extensions/shortcuts頁(yè)面顯示為可手動(dòng)修改所以測(cè)試時(shí)如果沒(méi)有生效先去看看是不是被其他軟件或插件搶占了快捷鍵。4.4 options_page 與 options_ui設(shè)置頁(yè)的兩種形態(tài)設(shè)置頁(yè)面有兩種聲明方式。options_page是老的寫(xiě)法設(shè)置頁(yè)會(huì)作為獨(dú)立的標(biāo)簽頁(yè)打開(kāi)相當(dāng)于一個(gè)完整的網(wǎng)頁(yè)這個(gè)頁(yè)面里可以自由使用chrome.*API。options_ui是新寫(xiě)法可以配合open_in_tab: false讓設(shè)置頁(yè)在一個(gè)嵌入式面板中打開(kāi)。兩者都只能出現(xiàn)一個(gè)同時(shí)寫(xiě)進(jìn) manifest 的話 Chrome 會(huì)優(yōu)先使用options_ui的設(shè)置。options_ui: { page: options.html, open_in_tab: true }如果用嵌入式設(shè)置頁(yè)最好不要在options.html里使用window.close()這類(lèi)操作因?yàn)轫?yè)面不是在獨(dú)立標(biāo)簽頁(yè)中打開(kāi)關(guān)閉邏輯可能不受控。另外有些插件希望讓用戶(hù)右鍵圖標(biāo)菜單里直接進(jìn)設(shè)置頁(yè)這個(gè)需要你在chrome.runtime.openOptionsPage()里手動(dòng)觸發(fā)即便沒(méi)有寫(xiě)options_ui這個(gè)函數(shù)依然可用因?yàn)?Chrome 會(huì)自動(dòng)兜底。5. 權(quán)限和資源聲明MV3 最容易審核被拒的區(qū)域5.1 permissions 和 host_permissions怎么寫(xiě)才既不報(bào)錯(cuò)也不過(guò)度索權(quán)permissions里的 API 權(quán)限非常多開(kāi)發(fā)中最常用的大概是這些storage使用chrome.storage.local或chrome.storage.session存取數(shù)據(jù)scripting使用chrome.scripting.executeScript/insertCSS動(dòng)態(tài)注入腳本activeTab用戶(hù)主動(dòng)交互時(shí)獲得當(dāng)前標(biāo)簽頁(yè)的臨時(shí)訪問(wèn)權(quán)限tabs讀取標(biāo)簽頁(yè)的 url、title 等敏感信息不需要注入腳本時(shí)常常沒(méi)必要申請(qǐng)alarms使用定時(shí)器clipboardRead/clipboardWrite讀寫(xiě)剪貼板downloads主動(dòng)觸發(fā)下載notifications桌面通知?jiǎng)e把permissions當(dāng)成許愿池凡是你能想到的 API 全往上堆。Chrome Web Store 審核時(shí)會(huì)評(píng)估權(quán)限是否合理申請(qǐng)了一堆用不到的權(quán)限會(huì)被打回。而且權(quán)限多用戶(hù)在安裝時(shí)看到的警告信息也多很影響轉(zhuǎn)化率。我見(jiàn)過(guò)有些插件只是做個(gè)網(wǎng)頁(yè)高亮標(biāo)注卻申請(qǐng)了tabs和all_urls這些權(quán)限完全可以通過(guò)activeTab按需獲取。host_permissions則用來(lái)聲明腳本能運(yùn)行在哪些站點(diǎn)上。注意如果你同時(shí)在content_scripts里寫(xiě)了matches那么host_permissions的作用不是重復(fù)聲明匹配規(guī)則而是讓你的插件在后臺(tái) Service Worker 和彈窗頁(yè)面里也能進(jìn)行跨域請(qǐng)求、使用chrome.tabs.query讀取這些站點(diǎn)的標(biāo)簽數(shù)據(jù)等。也就是說(shuō)content_scripts 匹配規(guī)則和 host_permissions 是兩套體系后者決定插件自身的代碼能訪問(wèn)哪些網(wǎng)絡(luò)資源前者決定注入到頁(yè)面里的腳本能出現(xiàn)在哪些頁(yè)面。一個(gè)比較常見(jiàn)的組合是使用activeTabscripting來(lái)代替all_urls的權(quán)限申請(qǐng)。這樣用戶(hù)點(diǎn)擊插件圖標(biāo)時(shí)你的腳本才被注入到當(dāng)前頁(yè)面不需要提前聲明所有域名。這個(gè)方案在權(quán)限審查上極其友好缺點(diǎn)是用戶(hù)第一次使用時(shí)不夠自動(dòng)需要多點(diǎn)一下圖標(biāo)。5.2 web_accessible_resources語(yǔ)義從可訪問(wèn)資源變成特定頁(yè)面可用資源MV2 的web_accessible_resources就是一個(gè)簡(jiǎn)單的資源路徑數(shù)組聲明了之后任何網(wǎng)站上的腳本都可以通過(guò)chrome.runtime.getURL拿到這些資源的地址并訪問(wèn)。這在當(dāng)時(shí)引發(fā)了很多濫用比如惡意網(wǎng)站可以通過(guò)訪問(wèn)你的插件資源來(lái)探測(cè)你是否安裝了某個(gè)插件。MV3 把整個(gè)機(jī)制改了變成對(duì)象數(shù)組每個(gè)對(duì)象里必須包含resources和matches表示這些資源只允許在這些匹配的頁(yè)面里被訪問(wèn)。web_accessible_resources: [ { resources: [injected.js, images/*.png], matches: [https://*.example.com/*] } ]這個(gè)字段通常和content_scripts中注入的腳本配合使用你的內(nèi)容腳本想要?jiǎng)討B(tài)加載插件里的某個(gè)資源就得把該資源聲明為 web accessible否則頁(yè)面端的 JavaScript 無(wú)法讀取。還有一個(gè)新屬性u(píng)se_dynamic_url把它設(shè)為true時(shí)Chrome 每次啟動(dòng)插件會(huì)生成一個(gè)隨機(jī)的資源路徑前綴可以防止網(wǎng)站固定路徑來(lái)探測(cè)插件。這個(gè)屬性特別適合做隱私保護(hù)類(lèi)插件值得用起來(lái)。5.3 content_security_policyMV3 里它基本沒(méi)有發(fā)揮空間正如 2.3 節(jié)說(shuō)的MV3 下content_security_policy已經(jīng)變成content_security_policy: { extension_pages: script-src self; object-src self;, sandbox: sandbox allow-scripts; script-src self unsafe-eval }如果你沒(méi)有特殊的沙盒需求可以完全不聲明extension_pagesChrome 會(huì)使用默認(rèn)策略。一旦你自己聲明了就只能比默認(rèn)策略更嚴(yán)格不能更寬松所以沒(méi)必要去填一個(gè)和默認(rèn)一樣的值。如果你真的需要eval或者new Function來(lái)動(dòng)態(tài)執(zhí)行代碼那就得把相關(guān)頁(yè)面聲明為sandbox。比如你在插件目錄下建了一個(gè)sandbox.html然后在sandbox里給它指定 CSP就可以在這個(gè)頁(yè)面里自由執(zhí)行eval但這個(gè)頁(yè)面不能直接調(diào)用chrome.*API只能通過(guò)postMessage和父頁(yè)面通信。我在做模板渲染工具時(shí)就是這么干的渲染邏輯放在沙盒頁(yè)面數(shù)據(jù)通過(guò)消息傳給父頁(yè)面對(duì)于合法用途來(lái)說(shuō)這個(gè)是可行的但絕大多數(shù)情況你應(yīng)該用正常的函數(shù)引用或Function.prototype的安全替代方案避免引入代碼注入風(fēng)險(xiǎn)。5.4 optional_permissions 與 optional_host_permissions把權(quán)限申請(qǐng)延后到運(yùn)行時(shí)這兩個(gè)字段在 MV3 里同樣存在作用是聲明插件可能需要的權(quán)限但安裝時(shí)不會(huì)提示等到用戶(hù)實(shí)際操作到對(duì)應(yīng)功能時(shí)通過(guò)chrome.permissions.request接口彈窗申請(qǐng)。這種模式可以顯著降低首次安裝的心理門(mén)檻。optional_permissions: [downloads], optional_host_permissions: [https://api.example.com/*]要注意optional_permissions里的權(quán)限不能和permissions里的重復(fù)用戶(hù)一旦授予了可選權(quán)限之后chrome.permissions.remove可以再取消。如果你的插件核心功能需要某個(gè)權(quán)限盡量不要把它放到 optional 里否則用戶(hù)拒絕授權(quán)你的主流程就跑不通了。合理用法是核心權(quán)限在安裝時(shí)聲明周邊功能權(quán)限比如導(dǎo)出 PDF要用到downloads可以推遲到用戶(hù)點(diǎn)擊導(dǎo)出按鈕時(shí)再申請(qǐng)。6. 那些容易被忽略的邊緣字段與綜合配置示例6.1 minimum_chrome_version、incognito、externally_connectableminimum_chrome_version指定你的插件最低能支持的 Chrome 版本。MV3 本身要求 Chrome 88 及以上但如果你用到了更新的 API比如chrome.scripting中較新的方法就要把最低版本調(diào)高。這個(gè)字段常常被忽略導(dǎo)致部分老版本瀏覽器用戶(hù)反饋插件裝上了但功能不生效我在自己插件里就把minimum_chrome_version設(shè)成了109因?yàn)檫@個(gè)版本之后 MV3 的穩(wěn)定性才真正到位。incognito字段控制插件在無(wú)痕模式下的表現(xiàn)取值有spanning默認(rèn)在有痕和無(wú)痕模式間共享、split每個(gè)模式單獨(dú)運(yùn)行一個(gè)后臺(tái)、not_allowed無(wú)痕模式下完全禁用。如果你的插件需要緩存一些用戶(hù)數(shù)據(jù)最好明確設(shè)為split避免隱私數(shù)據(jù)在無(wú)痕和有痕之間串臺(tái)。externally_connectable字段用于聲明哪些外部擴(kuò)展或網(wǎng)站可以通過(guò)chrome.runtime.connect或chrome.runtime.sendMessage給你的插件發(fā)消息。配置時(shí)可以用ids指定擴(kuò)展 ID也可以用matches指定網(wǎng)頁(yè)域名。這個(gè)字段安全相關(guān)建議收斂到最小范圍不寫(xiě)的話默認(rèn)為不允許任何外部來(lái)源通信。6.2 一份可直接復(fù)制修改的最小完整 Manifest.json把前面講的字段綜合到一起給出一個(gè)我目前線上插件實(shí)際在用的配置骨架{ manifest_version: 3, name: 我的網(wǎng)頁(yè)助手指南, version: 1.2.0, description: 一個(gè)用于網(wǎng)頁(yè)標(biāo)注與數(shù)據(jù)提取的示例插件, minimum_chrome_version: 109, icons: { 16: icons/icon16.png, 32: icons/icon32.png, 48: icons/icon48.png, 128: icons/icon128.png }, action: { default_popup: popup/popup.html, default_title: 打開(kāi)助手 }, background: { service_worker: background/service-worker.js, type: module }, content_scripts: [ { matches: [https://*/*, http://*/*], js: [content/content.js], run_at: document_idle, world: ISOLATED } ], permissions: [storage, scripting, activeTab], host_permissions: [https://*/, http://*/], web_accessible_resources: [ { resources: [injected/injected.js], matches: [https://*/*, http://*/*], use_dynamic_url: true } ], options_ui: { page: options/options.html, open_in_tab: false }, commands: { toggle-annotation: { suggested_key: { default: AltShiftA }, description: 切換標(biāo)注模式 } } }這份配置覆蓋了絕大多數(shù)插件的核心需求。你要根據(jù)自己的功能刪減不需要它就用不到不要照抄。6.3 加載與排錯(cuò)流程從本地加載到控制臺(tái)報(bào)錯(cuò)定位寫(xiě)完 Manifest.json 后打開(kāi)chrome://extensions開(kāi)啟右上角的開(kāi)發(fā)者模式點(diǎn)擊加載已解壓的擴(kuò)展程序選擇插件目錄。如果 Manifest.json 有 JSON 語(yǔ)法錯(cuò)誤或字段校驗(yàn)不通過(guò)這里會(huì)直接給出報(bào)錯(cuò)信息具體到哪個(gè)字段有問(wèn)題照著改就行。如果提示清單文件缺失或不可讀先檢查文件編碼不要用帶 BOM 的 UTF-8Chrome 對(duì) BOM 的容忍度比較低。加載成功后去擴(kuò)展詳情頁(yè)點(diǎn)擊查看錯(cuò)誤按鈕能看到 Service Worker 和各個(gè)頁(yè)面的報(bào)錯(cuò)日志。我在調(diào)試時(shí)遇到過(guò)一個(gè)詭異現(xiàn)象插件明明加載成功了但一點(diǎn)擊圖標(biāo)就縮回去沒(méi)任何反應(yīng)。打開(kāi)錯(cuò)誤面板才發(fā)現(xiàn)是popup.html里引用的一個(gè)本地 JS 文件因?yàn)槁窂綄?xiě)錯(cuò) 404 了而彈窗頁(yè)面一有 JS 錯(cuò)誤就會(huì)自動(dòng)關(guān)閉表現(xiàn)的就像點(diǎn)了沒(méi)反應(yīng)。這類(lèi)問(wèn)題排查時(shí)錯(cuò)誤信息面板比什么都好使。7. 我實(shí)際踩過(guò)的坑和最終的排錯(cuò)結(jié)論說(shuō)實(shí)話Manifest.json 的字段本身不算復(fù)雜真正麻煩的是 MV3 整體架構(gòu)改變帶來(lái)的連鎖反應(yīng)。有幾個(gè)坑我特別想單獨(dú)拎出來(lái)說(shuō)因?yàn)樗鼈冊(cè)诠俜轿臋n里不會(huì)寫(xiě)但幾乎每個(gè)遷移者都會(huì)遇到。第一個(gè)坑是content_scripts里用了include_globs后發(fā)現(xiàn)腳本就是不在預(yù)期頁(yè)面上運(yùn)行。include_globs和exclude_globs是匹配模式的補(bǔ)充規(guī)則格式和 glob 相似比如*://*.example.com/*。但它們和matches的交集邏輯比較繞只有同時(shí)滿足 matches 和 globs 規(guī)則才會(huì)注入。如果你習(xí)慣了只寫(xiě) matches突然加了 globs反而會(huì)縮小注入范圍。我的建議是能用 matches 解決的絕不寫(xiě) globs否則調(diào)試時(shí)很容易懷疑人生。第二個(gè)坑是 MV3 下沒(méi)法在插件內(nèi)部使用XMLHttpRequest訪問(wèn)普通 HTTP 接口必須使用fetch。這個(gè)不是 Manifest.json 字段的問(wèn)題但很多人把報(bào)錯(cuò)Service worker cannot use XMLHttpRequest當(dāng)成 manifest 配置錯(cuò)誤翻遍配置文件也找不到答案。實(shí)際上這是 Service Worker 環(huán)境的限制改用fetch即可。第三個(gè)坑最隱蔽某些 API 在 MV3 的permissions里寫(xiě)錯(cuò)了也不報(bào)錯(cuò)功能卻靜默失敗。比如我用chrome.storage.sync時(shí)忘了在 permissions 里聲明storage結(jié)果是同步功能完全不生效但瀏覽器控制臺(tái)里不打印任何錯(cuò)誤只有在你調(diào)用chrome.runtime.lastError檢查時(shí)才會(huì)看到。所以寫(xiě)完 manifest 后建議逐個(gè)功能點(diǎn)走一遍并且通過(guò)chrome.runtime.lastError檢查異步調(diào)用是否真的成功。最后一個(gè)排錯(cuò)結(jié)論如果插件在chrome://extensions頁(yè)面加載時(shí)報(bào)Extension must be signed in to use this API或者一些莫名其妙的錯(cuò)誤優(yōu)先看你是不是同時(shí)開(kāi)了 Chrome 的多用戶(hù)配置、或者用了企業(yè)策略限制了擴(kuò)展權(quán)限。這些情況下的報(bào)錯(cuò)信息往往指向 manifest 字段但根源其實(shí)在瀏覽器運(yùn)行環(huán)境別在上面空耗時(shí)間。Manifest V3 的遷移陣痛是真實(shí)的但理解它背后的安全優(yōu)先、資源友好思路之后你會(huì)發(fā)現(xiàn)每個(gè)字段限制都有它存在的理由。上面這些內(nèi)容是我自己在遷移兩個(gè)生產(chǎn)插件過(guò)程中邊看文檔邊試錯(cuò)總結(jié)出來(lái)的希望你能避開(kāi)我走過(guò)的彎路花更少的時(shí)間把 Manifest.json 一次寫(xiě)對(duì)。