簡單建立一個瀏覽器插件 Chrome Extension (manifest V3)

10 min readDec 15, 2023

介紹

Google Chrome Extension（Google Chrome 擴展程序）是一種用於 Google Chrome 瀏覽器的外掛系統，它允許開發者通過新增額外的功能和定製選項來擴展瀏覽器的功能(廣告攔截、翻譯、背景顏色變深、管理書籤...etc)。

要開發 Google Chrome Extension，需要一些基本的前端開發知識(HTML、CSS 和 JavaScript)

本文內容

最簡單做出 Chrome Extension 的方式
Chrome Extension 設定面補充(manifest.json、封裝拓展)
Chrome Extension 開發面補充

最簡單建立Chrome Extension的方式

1.建立資料夾結構

在一個新的資料夾中建立以下檔案：

manifest.json
popup.html
popup.js
images/icon.png (插件的圖標檔案)

2. 更改檔案內容

manifest.json

{
    "manifest_version": 3,
    "name": "Simple Extension",
    "version": "1.0",
    "description": "A simple Google Chrome Extension using Manifest V3",
    "permissions": [
        "storage"
    ],
    "action": {
        "default_popup": "popup.html",
        "default_icon": {
            "16": "images/icon.png",
            "48": "images/icon.png",
            "128": "images/icon.png"
        }
    }
}

popup.html

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Simple Extension Popup</title>
    <script src="popup.js"></script>
</head>

<body>
    <h1>如何建立一個Chrome插件 (Chrome extensions manifest V3)</h1>
</body>

</html>

popup.js

console.log("Popup script loaded!");

3.載入到Google Chrome

到編輯拓展的頁面(在瀏覽器的網址上輸入 chrome://extensions/ )

點擊"載入未封裝項目"，選剛剛建立的檔案的資料夾案確定，就完成上傳了。接著可以在右上角的擴充功能按鈕找到上傳的插件

Chrome Extension 設定面補充

1. manifest.json

manifest.json 是 Google Chrome Extension 中用於描述和組態擴展程序的清單檔案，用於告訴瀏覽器如何處理擴展程序。也包含了有關擴展程序的基本資訊，如名稱、版本、權限、圖示等。

以下是剛剛使用到的manifest.json範例，介紹一下常見的參數

{
    "manifest_version": 3, 
    "name": "Simple Extension",
    "version": "1.0",
    "description": "A simple Google Chrome Extension using Manifest V3",
    "permissions": [
        "storage"
    ],
    "action": {
        "default_popup": "popup.html",
        "default_icon": {
            "16": "images/icon.png",
            "48": "images/icon.png",
            "128": "images/icon.png"
        }
    }
}

manifest_version : 指定擴充功能使用的 Manifest 版本
(2022年6月開始已不能在上傳v2的拓展到Store了，未來也可能全面取消v2的支援)

name : 擴充的主要名稱

version : 用於自訂當前擴充的版本號(幫助用戶和開發者瞭解擴充功能的變更)

description : 提供對擴充功能的簡短描述

permissions : 指定擴充功能所需的權限，這是一個陣列
(指定擴充功能所需的權限，像是是否允許讀取和寫入剪貼板、訪問瀏覽器的 Cookies...等)

action: 定義瀏覽器工具欄中的擴充功能圖示和行為
(指定拓展的圖示來源、點擊拓展圖示後彈出的html...等)

遵循權限最小化的原則

上面有提到可以在 permissions 參數中聲明所需要的權限，如果一次把所有能寫的全部都聲明(例如不需要複製剪貼簿但還是聲明了這個 permission )，雖然這不會導致功能上的問題，但當擴充功能需要某些權限時，Chrome 會提示用戶是否允許這些權限。如果擴充功能聲明了很多並未實際使用的權限，User可能會感到困惑並擔心隱私風險。

name & description 會顯示的位置

2. 如何封裝拓展

一樣到chrome://extensions/，接著點擊"封裝擴充功能"，選擇對應的檔案路徑就可以了。

封裝擴充功能完成後，會產生兩個檔案：.crx 與 .pem

.crx：擴充功能壓縮後的檔案，它包含了擴充功能的原始程式碼、資原始檔、圖示以及 Manifest 檔案等。

.pem： Chrome 擴充功能相關的金鑰檔案，其中包含用於簽署和驗證擴充功能的私鑰。這是一個保護擴充功能完整性和身份的關鍵檔案。.pem 檔案用於簽署擴充功能的 .crx 檔案。目的是確保擴充功能的真實性，防止內容被篡改，應當只有開發者擁有。後續要每次封裝時都會需要一開始產生的 .pem 檔案，要好好保存。

為什麼要封裝？

確保檔案結構的一致性和完整性
如果有預計將擴充功能上傳至 Chrome Web Store，則必須封裝
方便分享給其他人 (若沒有封裝但要分享給其他人，就只能整個資料夾傳給對方。但封裝完成後只要把封裝完成的.crx檔案傳給對方，對方將檔案拖曳到擴充功能頁面，系統就會提示是否要新增)

Chrome Extension 開發面補充

1. Debug

(開發中)VS Code 可安裝 "Live Server"，當保存開發中的 Html 時，Live Server 會自動重新加載，可以透過 Live Server 及時預覽當前開發的畫面。

(使用中)打開拓展後點擊滑鼠右鍵案"檢查"即可開啟開發者模式。

2. 常見錯誤

Refused to execute inline script because it violates the following Content Security Policy directive: “script-src ‘self’ ‘wasm-unsafe-eval’ ‘inline-speculation-rules’ http://localhost:* http://127.0.0.1:*". Either the ‘unsafe-inline’ keyword, a hash (‘sha256-…’), or a nonce (‘nonce-…’) is required to enable inline execution.

這個錯誤是來自於當前的拓展使用了內聯的 Script，違反 CSP 的規則。Content Security Policy（CSP）是一種網站安全性標準，它是一組瀏覽器機制，用於減少或防止特定類型的攻擊。

以下提供一份會報相同錯誤的程式碼：

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Simple Extension Popup</title>
</head>

<body>
    <h1>如何建立一個Chrome插件 (Chrome extensions manifest V3)</h1>
    <script>
        alert('hello world');
    </script>
</body>

</html>

上述程式碼就違反了 CSP 的規則，因為 <body> 中含有內聯腳本。

解決方法是將腳本移至外部檔案，如：

// .index.html
<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Simple Extension Popup</title>
    <script src="popup.js"></script>
</head>

<body>
    <h1>如何建立一個Chrome插件 (Chrome extensions manifest V3)</h1>
</body>

</html>

//.popup.js
alert('hello world');

在上述的例子我們把原先要執行的alert從body中移到了popup.js，從而避免了 CSP 對內聯腳本的限制。

將腳本移至外部檔案為什麼就可以避免違反 CSP ?

CSP 限制內聯腳本的執行，主要是為了防止跨站腳本攻擊（XSS）。攻擊者可能會試圖注入惡意腳本，並使之在受害者瀏覽器中執行。透過將腳本移至外部檔案，CSP 就能夠更容易地控制腳本的來源，並確保只有受信任的來源可以提供腳本。

此外，外部腳本也提供了更好的可讀性和維護性，若都把Script寫在單一html中，程式很容易就過於複雜，而將腳本獨立在外部檔案中。也使得代碼更易於理解，更容易進行修改和測試。

3. 安全性提醒

不要把API 金鑰或是其他敏感資料硬編碼於程式碼中，若要包含敏感資料，請使用安全的方式，例如存儲在擴展程式的背景頁或使用外部組態檔案。

本文僅是簡單介紹如何新增插件 Popup 視窗，後續會繼續說明如何對頁面元素進行操作 (如：新增自訂的右鍵選單、插入自訂元素到當前畫面、自動填入表單值、自動提交表單...等)

可接續參考下一篇文章簡單開發瀏覽器插件 Chrome Extension

簡單建立一個瀏覽器插件 Chrome Extension (manifest V3)

最簡單建立Chrome Extension的方式

Chrome Extension 設定面補充

Chrome Extension 開發面補充

Written by Ray

No responses yet