1. 為什么現(xiàn)在還要重新啃 Manifest.jsonMV3 的一場(chǎng)強(qiáng)制遷徙2023 年初開始Chrome Web Store 就關(guān)閉了 Manifest V2 插件的新提交通道到 2024 年更是全面停止了對(duì) MV2 擴(kuò)展的支持。這意味著什么如果你手上還有一套用browser_action、background.scripts寫的老插件哪怕它運(yùn)行得好好的也會(huì)在用戶瀏覽器里被強(qiáng)制禁用取而代之的是一個(gè)灰色圖標(biāo)加上已停用的提示。很多開發(fā)者就是在這個(gè)節(jié)點(diǎn)上被迫開始讀 Manifest.json 文檔的我也不例外。當(dāng)時(shí)我手上有三個(gè)線上插件要遷移翻遍官方文檔和各類碎片文章發(fā)現(xiàn)了一個(gè)尷尬的事實(shí)Manifest V3 的字段說(shuō)明散落在不同頁(yè)面很少有文章能從頭到尾把所有字段講清楚更沒有幾篇能告訴你這個(gè)字段在 MV3 里已經(jīng)改了、那個(gè)字段千萬(wàn)別照舊填。如果你正準(zhǔn)備開發(fā)一個(gè)新的 Chrome 插件或者正在為老插件做遷移那么 Manifest.json 就是你繞不開的第一道門。它不只是一個(gè)聲明文件它決定了你的插件能拿到什么權(quán)限、能跑哪些代碼、能在什么頁(yè)面里注入腳本、UI 長(zhǎng)什么樣。我在做遷移的過(guò)程中因?yàn)樽侄卫斫馄畈攘瞬簧倏佑行┛釉诠俜轿臋n里壓根不會(huì)寫。這篇文章我就按照自己實(shí)際操作過(guò)的順序把 MV3 版本 Manifest.json 的字段從頭到尾拆一遍重點(diǎn)標(biāo)注那些和 MV2 差異巨大、特別容易翻車的地方。文章適合三種人第一次寫插件的新手、從 MV2 遷移的老手、以及想在發(fā)布前自查一遍配置細(xì)節(jié)的開發(fā)者。在進(jìn)入逐字段分析之前先想明白一件事MV3 的整體設(shè)計(jì)思路說(shuō)白了就是收緊權(quán)限、消滅常駐后臺(tái)、禁止遠(yuǎn)程代碼。這三個(gè)原則幾乎解釋了 Manifest.json 里所有字段的增刪改變化。你只有把這三個(gè)原則刻在腦子里再看字段列表時(shí)就不會(huì)覺得有些限制莫名其妙了。2. 三個(gè)看不見但決定一切的 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)聽事件、維護(hù)狀態(tài)、處理消息。這個(gè)頁(yè)面只要瀏覽器開著就會(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字段的寫法完全不同了。MV2 里常見的是background: {scripts: [bg.js], persistent: true}到了 MV3 變成background: {service_worker: bg.js}。別小看這個(gè)變化persistent字段整個(gè)消失了因?yàn)?MV3 里不存在持久后臺(tái)的概念而且service_worker只能指定一個(gè)文件不能再像 MV2 那樣寫一個(gè)數(shù)組。如果你想按模塊拆分代碼需要在background.service_worker.type里設(shè)置為module用 ES Module 的方式來(lái)組織代碼。我剛遷移時(shí)在這個(gè)坑里卡了兩天我把老代碼拆成了background.js和utils.js兩個(gè)文件按照 MV2 的慣性把它們寫進(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 寫法就是跑不通。2.2 權(quán)限邊界大幅收窄h(huán)ost_permissions 被單獨(dú)拎出來(lái)MV2 里所有權(quán)限都堆在一個(gè)permissions數(shù)組里包括tabs、storage、http://*/這類站點(diǎn)權(quán)限。MV3 把訪問(wèn)哪些網(wǎng)站這種高危權(quán)限單獨(dú)拆成了一個(gè)字段host_permissions和permissions分開放置。邏輯很清楚permissions管的是 Chrome 提供的 API 能力比如storage存儲(chǔ)、alarms定時(shí)器、clipboardRead讀剪貼板而host_permissions管的是你的腳本能跑在哪些域名上比如https://*.example.com/*。為什么要這么拆因?yàn)樵?Chrome 的權(quán)限提示 UI 里用戶可以清楚地看到這個(gè)插件能讀取你在所有網(wǎng)站上的數(shù)據(jù)而不會(huì)把它和插件能使用存儲(chǔ) API混為一談。如果你只聲明了host_permissions而沒有在permissions里聲明對(duì)應(yīng) API那么你能往頁(yè)面上注入腳本但未必能調(diào)用chrome.storage反過(guò)來(lái)你聲明了storageAPI 權(quán)限但沒聲明任何host_permissions你的腳本就哪兒也去不了。這兩個(gè)字段是配合關(guān)系不是替代關(guān)系。我在給一個(gè)網(wǎng)頁(yè)標(biāo)注工具做遷移時(shí)把permissions: [activeTab, scripting, storage, https://*/*]直接復(fù)制到了 MV3Chrome 倒是沒報(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ì)讓你在用戶主動(dòng)點(diǎn)擊插件圖標(biāo)時(shí)獲得當(dāng)前標(biāo)簽頁(yè)的一次性訪問(wèn)權(quán)。能少聲明就少聲明審核更容易通過(guò)用戶安裝時(shí)的安全感也更強(qiáng)。2.3 遠(yuǎn)程代碼全面禁止CSP 規(guī)則從字符串變成對(duì)象MV2 時(shí)代在content_security_policy里你可以寫script-src self https://some-cdn.com;然后直接在插件頁(yè)面里引入遠(yuǎn)程 CDN 的腳本。MV3 一刀切了推廣線上 CSP 只允許self不允許任何遠(yuǎn)程源、不允許eval、不允許wasm-eval。這意味著你的插件代碼、依賴庫(kù)、所有邏輯都必須打包進(jìn)插件本地的文件里想在運(yùn)行時(shí)從服務(wù)器拉腳本沒門。對(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;幾乎沒有操作空間sandbox才是留給你自由發(fā)揮的空間如果你需要做一些不安全的操作比如通過(guò)eval執(zhí)行動(dòng)態(tài)代碼可以讓這些代碼在沙盒頁(yè)面里跑。我之前寫過(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 下必須寫整數(shù)3而且必須是數(shù)字類型不能寫字符串3。這是 Chrome 在解析時(shí)直接強(qiáng)校驗(yàn)的寫錯(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不合法。很多開發(fā)者在這里翻車是因?yàn)樗麄冇萌掌诋?dāng)版本號(hào)比如2024.12.31看起來(lá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)先加載用戶瀏覽器語(yǔ)言對(duì)應(yīng)的 messages 文件找不到再回退到默認(rèn)語(yǔ)言。key字段可能是所有字段里最容易被誤解的一個(gè)。它不是你在 Manifest.json 里手寫的而是 Chrome 在你打包插件時(shí)生成的。它的作用是固定插件的 ID這樣無(wú)論用戶從商店安裝還是你用--load-extension本地加載插件 ID 都是一樣的。這對(duì)依賴固定 ID 的開發(fā)場(chǎng)景特別重要比如你通過(guò)externally_connectable讓別的擴(kuò)展和自己通信時(shí)ID 變了就全斷了。如果你在開發(fā)環(huán)境里發(fā)現(xiàn)插件 ID 每次刷新都不一樣那大概率是沒設(shè)置key字段。怎么拿 key先在瀏覽器里加載一次未打包的擴(kuò)展然后在chrome://extensions頁(yè)面開啟開發(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 所在目錄的不要用../這種寫法會(huì)解析失敗。4. 核心功能字段全面拆解從 background 到 content_scripts 到 action4.1 background.service_worker注冊(cè)規(guī)則與生命周期控制在 MV3 里background字段最常見的寫法是這樣background: { service_worker: service-worker.js, type: module }service_worker的值是相對(duì)于插件根目錄的路徑。type設(shè)為module時(shí)這個(gè) worker 會(huì)以 ES Module 的身份執(zhí)行你可以在里面用import語(yǔ)句引入其他模塊這是目前最推薦的寫法。但注意MV3 的 Service Worker 有幾個(gè)和普通頁(yè)面腳本完全不同的特性理解它們才能正確配置字段它是事件驅(qū)動(dòng)的空閑約 30 秒就會(huì)被終止。所以你不能在 worker 里掛一個(gè)全局變量長(zhǎng)期保存狀態(tài)狀態(tài)要存到chrome.storage或 IndexedDB。監(jiān)聽器必須在頂層同步注冊(cè)。如果你在chrome.runtime.onInstalled.addListener的回調(diào)里再注冊(cè)其他事件的監(jiān)聽worker 休眠后這些監(jiān)聽器可能丟失。在 worker 里訪問(wèn) DOM 是不行的document、window這些對(duì)象都不存在。我早期犯過(guò)一個(gè)錯(cuò)我在 worker 里用了setInterval定時(shí)去輪詢接口想著這跟 MV2 的后臺(tái)頁(yè)一樣會(huì)一直跑。結(jié)果每次休眠喚醒后定時(shí)器就斷了甚至接口請(qǐng)求都會(huì)因?yàn)?CORS 問(wèn)題失敗。后來(lái)我把定時(shí)任務(wù)改成使用chrome.alarmsAPI配合chrome.storage存儲(chǔ)上一次的輪詢時(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ī)則寫法是 Chrome 匹配模式match pattern比如https://*/*、http://localhost/*、all_urls。注意不要在matches里出現(xiàn)http://localhost:8080/*這種帶端口的寫法端口在匹配模式里是不支持的如果你要匹配本地開發(fā)地址得寫成http://localhost/*然后靠include_globs或 JS 里自行判斷端口。run_at有三個(gè)可選值document_startDOM 剛開始構(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ū)分工具欄按鈕一直可見和只在特定頁(yè)面可見Chrome 干脆合并了統(tǒng)一默認(rèn)可見然后用程序控制在特定頁(yè)面禁用按鈕。Manifest.json 里action字段的典型寫法action: { default_popup: popup.html, default_title: 點(diǎn)擊打開面板, 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)聽chrome.action.onClicked事件。注意一個(gè)坑一旦設(shè)置了default_popupchrome.action.onClicked事件就不會(huì)觸發(fā)了。有時(shí)我在調(diào)試時(shí)發(fā)現(xiàn)點(diǎn)擊按鈕沒反應(yīng)第一反應(yīng)是去看 onClicked 監(jiān)聽器結(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: 開關(guān)某項(xiàng)功能 } }當(dāng)你在 manifest 里聲明了commands需要在一個(gè)頁(yè)面里調(diào)用chrome.commands.onCommand.addListener來(lái)監(jiān)聽觸發(fā)并執(zhí)行對(duì)邏輯。系統(tǒng)快捷鍵有保留鍵位比如 CtrlShift某些特殊鍵如果沖突Chrome 會(huì)在chrome://extensions/shortcuts頁(yè)面顯示為可手動(dòng)修改所以測(cè)試時(shí)如果沒有生效先去看看是不是被其他軟件或插件搶占了快捷鍵。4.4 options_page 與 options_ui設(shè)置頁(yè)的兩種形態(tài)設(shè)置頁(yè)面有兩種聲明方式。options_page是老的寫法設(shè)置頁(yè)會(huì)作為獨(dú)立的標(biāo)簽頁(yè)打開相當(dāng)于一個(gè)完整的網(wǎng)頁(yè)這個(gè)頁(yè)面里可以自由使用chrome.*API。options_ui是新寫法可以配合open_in_tab: false讓設(shè)置頁(yè)在一個(gè)嵌入式面板中打開。兩者都只能出現(xiàn)一個(gè)同時(shí)寫進(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()這類操作因?yàn)轫?yè)面不是在獨(dú)立標(biāo)簽頁(yè)中打開關(guān)閉邏輯可能不受控。另外有些插件希望讓用戶右鍵圖標(biāo)菜單里直接進(jìn)設(shè)置頁(yè)這個(gè)需要你在chrome.runtime.openOptionsPage()里手動(dòng)觸發(fā)即便沒有寫options_ui這個(gè)函數(shù)依然可用因?yàn)?Chrome 會(huì)自動(dòng)兜底。5. 權(quán)限和資源聲明MV3 最容易審核被拒的區(qū)域5.1 permissions 和 host_permissions怎么寫才既不報(bào)錯(cuò)也不過(guò)度索權(quán)permissions里的 API 權(quán)限非常多開發(fā)中最常用的大概是這些storage使用chrome.storage.local或chrome.storage.session存取數(shù)據(jù)scripting使用chrome.scripting.executeScript/insertCSS動(dòng)態(tài)注入腳本activeTab用戶主動(dòng)交互時(shí)獲得當(dāng)前標(biāo)簽頁(yè)的臨時(shí)訪問(wèn)權(quán)限tabs讀取標(biāo)簽頁(yè)的 url、title 等敏感信息不需要注入腳本時(shí)常常沒必要申請(qǐng)alarms使用定時(shí)器clipboardRead/clipboardWrite讀寫剪貼板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)限多用戶在安裝時(shí)看到的警告信息也多很影響轉(zhuǎ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里寫了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è)比較常見的組合是使用activeTabscripting來(lái)代替all_urls的權(quán)限申請(qǐng)。這樣用戶點(diǎn)擊插件圖標(biāo)時(shí)你的腳本才被注入到當(dāng)前頁(yè)面不需要提前聲明所有域名。這個(gè)方案在權(quán)限審查上極其友好缺點(diǎn)是用戶第一次使用時(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)。5.3 content_security_policyMV3 里它基本沒有發(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 }如果你沒有特殊的沙盒需求可以完全不聲明extension_pagesChrome 會(huì)使用默認(rèn)策略。一旦你自己聲明了就只能比默認(rèn)策略更嚴(yán)格不能更寬松所以沒必要去填一個(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ì)提示等到用戶實(shí)際操作到對(duì)應(yīng)功能時(shí)通過(guò)chrome.permissions.request接口彈窗申請(qǐng)。這種模式可以顯著降低首次安裝的心理門檻。optional_permissions: [downloads], optional_host_permissions: [https://api.example.com/*]要注意optional_permissions里的權(quán)限不能和permissions里的重復(fù)用戶一旦授予了可選權(quán)限之后chrome.permissions.remove可以再取消。如果你的插件核心功能需要某個(gè)權(quán)限盡量不要把它放到 optional 里否則用戶拒絕授權(quán)你的主流程就跑不通了。合理用法是核心權(quán)限在安裝時(shí)聲明周邊功能權(quán)限比如導(dǎo)出 PDF要用到downloads可以推遲到用戶點(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)致部分老版本瀏覽器用戶反饋插件裝上了但功能不生效我在自己插件里就把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ú)痕模式下完全禁用。如果你的插件需要緩存一些用戶數(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)建議收斂到最小范圍不寫的話默認(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: 打開助手 }, 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ò)定位寫完 Manifest.json 后打開chrome://extensions開啟右上角的開發(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)就縮回去沒任何反應(yīng)。打開錯(cuò)誤面板才發(fā)現(xiàn)是popup.html里引用的一個(gè)本地 JS 文件因?yàn)槁窂綄戝e(cuò) 404 了而彈窗頁(yè)面一有 JS 錯(cuò)誤就會(huì)自動(dòng)關(guān)閉表現(xiàn)的就像點(diǎn)了沒反應(yīng)。這類問(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ì)寫但幾乎每個(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í)慣了只寫 matches突然加了 globs反而會(huì)縮小注入范圍。我的建議是能用 matches 解決的絕不寫 globs否則調(diào)試時(shí)很容易懷疑人生。第二個(gè)坑是 MV3 下沒法在插件內(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里寫錯(cuò)了也不報(bào)錯(cuò)功能卻靜默失敗。比如我用chrome.storage.sync時(shí)忘了在 permissions 里聲明storage結(jié)果是同步功能完全不生效但瀏覽器控制臺(tái)里不打印任何錯(cuò)誤只有在你調(diào)用chrome.runtime.lastError檢查時(shí)才會(huì)看到。所以寫完 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í)開了 Chrome 的多用戶配置、或者用了企業(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)的希望你能避開我走過(guò)的彎路花更少的時(shí)間把 Manifest.json 一次寫對(duì)。