跳轉到主要內容
跨瀏覽器、跨環境使用同一份擴充功能程式碼,不必把值寫死。

瀏覽器擴充功能中的環境變數

瀏覽器擴充功能會在使用者的機器上執行程式碼。這也讓「設定」與「機密」之間的界線比一般網頁應用更為敏感:任何安裝你擴充功能的人,都能讀出你打包到 JavaScript、HTML 或編譯後 manifest.json 中的內容。 Extension.js 用兩種環境載入路徑來處理這件事:一種服務 編譯後的擴充功能 bundle(會感知瀏覽器與模式),另一種則是在 Node 中載入 extension.config.* 時使用。 兩條路徑都重要,端視你要從哪裡讀取變數。

範本範例

new-env

new-env template screenshot 透過一個新分頁擴充功能(讀取 EXTENSION_PUBLIC_* 值)實際看看環境變數如何運作。
儲存庫:extension-js/templates/newtab-env

content-env

content-env template screenshot 在注入網頁的 content script 中使用環境變數。
儲存庫:extension-js/templates/content-env

運作方式

擴充功能 bundle(編譯時)

建置擴充功能時,編譯器會讀取你的擴充功能套件資料夾中符合瀏覽器與模式的 env 檔。從 4.1.41 之後的版本起,它會讀取每一個符合的檔案,較強的檔案逐鍵覆寫較弱的檔案。較早的版本只讀取最強的那一個符合檔案。由強到弱:
  1. .env.[browser].[mode](例如 .env.chrome.development)
  2. .env.[browser]
  3. 上述兩項的引擎家族變體(見下方說明)
  4. .env.[mode].local(從 4.1.41 之後的版本起)
  5. .env.[mode]
  6. .env.local
  7. .env
瀏覽器範圍的檔案依 引擎家族 解析,與瀏覽器專屬 manifest 欄位一致。在精確的瀏覽器名稱之後,Chromium 家族目標(chromium、chrome、edge、chromium-based、各 Chromium 分支以及 Safari 建置)還會依序嘗試 .env.chromium、.env.chrome、.env.edge 與 .env.chromium-based(各自的 .[mode] 變體優先)。Gecko 家族目標還會嘗試 .env.firefox 與 .env.gecko-based。因此一份 .env.chromium 檔即可涵蓋 chrome、edge 或 brave 建置,而精確的瀏覽器檔案永遠優先於家族檔案。 當 .env.defaults 存在時,Extension.js 一定會先合併 它,再合併各符合檔案的變數。最後,系統的 process.env 對重疊鍵擁有最高優先權。
.env.example 僅作為文件範例,永遠不會被當成值來源載入。
從 4.2.0 起,env 檔案是一個資料夾或無法讀取時,建置會以 E_ENV_FILE_UNREADABLE 停止。訊息會指名這個檔案。 如果專案旁存在 env 檔,但沒有任何一個符合目前的瀏覽器與模式,建置會印出警告,列出找到的檔案與查找過的候選檔名。這樣瀏覽器後綴的拼字錯誤會立刻暴露,而不是在沒有值注入的情況下悄悄完成建置。以另一個模式或瀏覽器命名的檔案,比如正式建置中的 .env.development,會被原樣留下且不印出警告。只有當沒有其他來源(比如 extension.config.js)定義這些值時,警告才會說它們是 undefined。 從 4.2.0 之後的版本開始,檔名以建置會發布或編譯的檔案副檔名結尾的檔案,比如 .env.css 或 .env.side.html,不算 env 檔,.envrc 也不算。這些副檔名不分大小寫,包括頁面(html、htm)、樣式表(css、scss、sass、less、styl)、腳本與元件(js、mjs、cjs、jsx、ts、mts、cts、tsx、vue、svelte)、資料與文字(json、json5、jsonc、xml、yml、yaml、toml、md、txt)、圖片(png、jpg、jpeg、gif、svg、webp、avif、ico、bmp)、字型(woff、woff2、ttf、otf、eot)、影音(mp3、mp4、webm、ogg、wav),以及 map、wasm、pdf 和 zip。這些檔案是以 .env 開頭的資源,所以警告不再指名它們,也不會只因為它們而印出。以瀏覽器或模式結尾的檔名,比如 .env.chrome 或 .env.production,一律算作 env 檔。

機密永遠不要使用 EXTENSION_PUBLIC_ 前綴

每一個 EXTENSION_PUBLIC_* 的值都會寫進建置出來的 JavaScript。任何安裝這個擴充功能的人都能讀到它,每一次商店審核也能。把 import.meta.env 當成整個物件讀取的程式碼會帶上所有公開值,包括它從未點名的那些。 LLM 或其他任何付費服務的 API key 應該放在你的擴充功能所呼叫的伺服器上。給它一個不帶 EXTENSION_PUBLIC_ 前綴的名字,這樣 bundle 裡永遠不會包含它。 當某個帶值的 EXTENSION_PUBLIC_* 變數的名字看起來像機密時,正式建置會發出警告。名字包含 SECRET、TOKEN、PASSWORD 或 PRIVATE 時看起來像機密。KEY 緊接在 API、ACCESS、AUTH 或 SECRET 之後時也是。包含 PUBLISHABLE 的名字會被略過。如果這個值本來就設計為公開,例如 Firebase 的 web API key,這則警告就不適用於它。這則警告需要 4.1.39 或更新的版本。 如果專案旁邊找不到符合的檔案,Extension.js 會從 最近的 workspace 根目錄 重複相同的搜尋。該根目錄是最近一個包含 pnpm-workspace.yaml 的祖先資料夾。Monorepo 中的擴充功能可以共用根層的 env 檔,用於 bundle 注入。唯一的 env 檔是 .env.defaults 的套件也會取用根目錄的檔案。根目錄的 .env.defaults 先載入,套件自己的 .env.defaults 逐鍵勝出。 Monorepo 限制: workspace fallback 只有在祖先目錄存在 pnpm-workspace.yaml 標記時才會執行。如果你使用純 npm 或 Yarn workspaces,只靠 package.json 的 "workspaces" 欄位,這套自動往上找的機制就不適用。這種情況下,請把 env 檔放在擴充功能套件旁邊,或在儲存庫根目錄加上 pnpm-workspace.yaml。

extension.config.*(Node,在你的設定執行前)

extension.config.js / .mjs / .cjs 會在 Node 中執行。Extension.js 在評估該檔案前,會預先載入 一小組 檔案到 process.env,讓設定檔可以讀取。從 4.1.41 之後的版本起,最後一個檔案跟隨所執行的指令。dev 讀取 development 檔案。build、start 與 preview 讀取 production 檔案。 每個存在的檔案都會載入,後面的檔案會覆寫前面檔案的值。shell 或 CI 匯出的變數永遠優先於所有檔案。讀取 import.meta.env 的 .mjs 設定檔看到的勝出值與 process.env 相同。build --mode development 讀取 development 檔案。 建置不再讀取 .env.development。只存在於該檔案中的鍵,在 build、start 與 preview 的設定裡是 undefined。4.1.41 及更早的版本會為每個指令預先載入 .env.development,所以建置的設定讀到的是開發環境的值。 從 4.1.41 之後的版本起,build、start 與 preview 也會預先載入瀏覽器的檔案,例如 .env.chrome 與 .env.chrome.production。設定因此看到與 bundle 相同的值。4.2.0 及更早的版本在知道瀏覽器之前就載入 dev 的設定,所以 dev 不讀取任何瀏覽器檔案。從 4.2.0 之後的版本起,dev 在第一次載入設定時就讀取瀏覽器的檔案,例如 .env.chrome 與 .env.chrome.development。 從 4.1.41 之後的版本起,extension.config.js 每個指令只執行一次。當設定本身指定瀏覽器時,它可能會執行第二次。只有在瀏覽器的檔案改變了它讀取的某個變數時才會這樣。 你也可以依賴 bundle 階段的 env(上述章節說明),把 EXTENSION_PUBLIC_* 的值注入到擴充功能程式碼裡。 Workspace fallback: 如果擴充功能套件資料夾中都沒有這些檔案,相同的預載會從最近一個包含 pnpm-workspace.yaml 的資料夾執行(限制與上方相同)。 從 4.1.41 之後的版本起,唯一的 env 檔是 .env.defaults 的套件也以同樣方式退回。根目錄的 .env.defaults 先載入,套件自己的 .env.defaults 逐鍵勝出。

內建環境變數

Extension.js 會在編譯時注入內建變數,讓你的擴充功能程式碼隨時都能取得瀏覽器與模式資訊。 以上所有內建變數,皆可透過 process.env.* 與 import.meta.env.* 取得。 Extension.js 在編譯時把這些名稱替換為它們的值。替換涵蓋你的檔案以及 bundle 中的每個相依套件。因此讀取 process.env.MODE 或 process.env.BROWSER 的相依套件會得到建置模式或瀏覽器目標。另外三個名稱也會這樣處理:
  • 程式碼沒有宣告的 global 會變成 globalThis。
  • import.meta.dirname 與 import.meta.filename 會變成 undefined。
從 4.1.41 之後的版本起,若某個 .env 檔把 EXTENSION_PUBLIC_BROWSER、EXTENSION_BROWSER、EXTENSION_PUBLIC_MODE 或 EXTENSION_MODE 設成其他值,建置會印出點名該檔案的 W_ENV_NAME_RESERVED 警告。建置目標勝出,因此檔案中的值被忽略。

環境變數總覽

公開/執行階段變數(使用者定義)

靜態佔位符變數

內建/別名變數

CLI 與開發伺服器的操作變數

從 4.1.39 之後的版本起,每個瀏覽器都依同一個順序解析執行檔。先是執行檔旗標,接著是變數、受管理的執行檔,最後是系統安裝。變數指向不存在或不可執行的路徑時,啟動會以 E_BROWSER_BINARY_INVALID 失敗。見執行檔如何選定。

遙測控制變數

EXTENSION_TELEMETRY=1 同時也是 CI 中的明確加入方式:在 CI 裡遙測預設是關閉的。完整的退出條款請參閱 遙測與隱私。

鷹架(extension create)變數

從 4.1.41 之後的版本起,EXTENSION_ALLOW_HTTP_TEMPLATE 與 EXTENSION_SKIP_INTERNAL_INSTALL 接受任意大小寫的 1 或 true,值兩側的空格會被忽略。更早的版本只接受 true。 釘選語料庫的運作方式請參閱範本。

瀏覽器傳輸調校變數

這些變數會覆寫 Chrome DevTools Protocol(CDP)與 Remote Debugging Protocol(RDP)內部逾時設定。對於緩慢的持續整合(CI)環境、Docker 容器,或除錯不穩定的瀏覽器連線特別有用。

瀏覽器專屬環境變數

下列規則適用於 編譯/bundle 時 的 env 選擇(請見上方的 擴充功能 bundle)。它們 不適用 於 Node 中那一小段 extension.config.* 的預載。 需要在不同瀏覽器使用不同的值?Extension.js 支援帶有瀏覽器範圍的 env 檔,例如 .env.chrome(Chrome 擴充功能環境變數)與 .env.firefox(Firefox 擴充功能環境變數)。你也可以結合瀏覽器與模式,對應到單一建置變體:
  • .env.chrome.development:僅在以 development 模式於 Chrome 執行擴充功能時套用。
  • .env.firefox.production:僅在以 production 模式為 Firefox 建置擴充功能時套用。
優先順序為:
  • .env.[browser].[mode]
  • .env.[browser]
  • 引擎家族變體(例如任何 Chromium 家族目標都會符合 .env.chromium)
  • .env.[mode]
  • .env.local
  • .env
你很少需要為每個廠商各建一個檔案。由於解析依引擎家族進行,.env.chromium 即可涵蓋 chrome、edge 及各 Chromium 分支,.env.firefox 則涵蓋各 Gecko 分支。只有當某個目標需要與家族其他成員不同的值時,才加上精確的瀏覽器檔案(例如 .env.edge)。

範例檔案

自訂環境變數

你可以在專案根目錄的 env 檔中定義自訂變數。
Extension.js 只會把以 EXTENSION_PUBLIC_ 為前綴的變數注入到 JavaScript bundle(process.env / import.meta.env)。
重要: Extension.js 不會把沒有 EXTENSION_PUBLIC_ 前綴的變數注入 JS bundle。
不過,輸出的 .json/.html 檔中的佔位符可以解析 $EXTENSION_* 標記,所以請避免在靜態資產樣板中引用機密。

使用環境變數

你可以在 manifest.json、語系檔、HTML 與 JavaScript/TypeScript 檔案中使用環境變數。

1. 在 manifest.json 中

manifest.json 本身不支援環境變數,但 Extension.js 會在建置時替換掉受支援的佔位符。例如:
編譯時,Extension.js 會把 $EXTENSION_PUBLIC_API_URL 取代為解析後的 env 值。 值會依它落腳的位置跳脫,所以輸出的檔案保持有效。在 JSON 字串裡,值中的引號或反斜線會被跳脫。在 HTML 文字與屬性裡,&、<、> 和引號會變成實體。在 <script> 的字串裡,值會依 JavaScript 字串跳脫。仍會破壞 JSON 檔案的值會讓建置以 E_JSON_INVALID 停止,訊息會指名該檔案與變數。

不讓本機來源進入正式 manifest

同樣的佔位符也能用在比對模式裡,開發用的模擬伺服器就是這樣留在商店套件之外的。把來源寫成佔位符,並為每種模式提供各自的值:
extension dev 讀取 .env.development,比對 http://localhost:4322/*。extension build 讀取 .env,只發佈 https://example.com/*。如果正式建置仍在 content_scripts、host_permissions、externally_connectable 或 web_accessible_resources 中寫著 localhost、127.0.0.1、[::1] 或 0.0.0.0,建置會印出代碼為 W_PROD_LOOPBACK_ORIGIN 的警告,並原樣發佈該模式,因為讓正式建置連到本機伺服器也可能是刻意的。

2. 在語系檔中

當值需要隨環境改變時,你也可以在語系檔中使用佔位符。例如:
當 Extension.js 輸出資產時,會把 $EXTENSION_PUBLIC_SITE_URL 等佔位符替換為解析後的值。 從 4.2.0 之後的版本開始,_locales/<locale>/messages.json 中緊接著第二個 $ 的記號,比如 $EXTENSION_MODE$,是瀏覽器自己的訊息佔位符,所以建置會保持原樣。

3. 在 HTML 檔中

你也可以在靜態 HTML 檔中使用佔位符(例如放在 pages/ 下):
編譯時,Extension.js 會替換輸出 HTML 中的 $EXTENSION_PUBLIC_API_URL。 從 4.2.0 之後的版本開始,建置會在它從專案中原樣複製的每個 .json 和 .html 檔案中填入同樣的佔位符。這包括 web_accessible_resources 中列出的檔案、背景透過 chrome.runtime.getURL() 開啟的檔案,以及透過根絕對連結(比如 /options.html)存取的頁面。每個值的跳脫方式與編譯後的頁面相同。沒有佔位符的複製檔案保留原樣的位元組。4.2.0 及之前的版本發布這些副本時,佔位符保持原樣。 從 4.2.0 之後的版本開始,沒有佔位符的輸出 .json 或 .html 檔案以原樣的位元組發布,不論其編碼。含有佔位符但不是 UTF-8 的檔案也以原樣發布,並帶有 W_ENV_ASSET_NOT_UTF8 警告。

4. 在 JSX 元件中

在 React/JSX/TS 檔案中,可以用 process.env 讀取 env 值:
Extension.js 會在編譯時將這些值內嵌進來,並可隨瀏覽器/模式變化。 從 4.2.0 起,process.env.EXTENSION_PUBLIC_X = "v" 這樣的寫入仍是有效程式碼,並在執行時寫到 env 物件上。對你自己的程式碼,建置會以 W_ENV_DEFINE_WRITTEN 警告,因為這個名稱的每一處點號讀取都保留建置時的值。執行時會變化的值請放進你自己的變數。

import.meta 支援

針對 ECMAScript Module(ESM)工作流程,Extension.js 也支援 import.meta.env:
service_worker.mjs
對於已注入的 env 鍵,import.meta.env 與 process.env 內容一致。 讀取任何 env 檔都未定義的鍵會得到 undefined,而不會當機:Extension.js 會把裸的 import.meta.env 定義為包含所有已注入變數的物件(與 Vite 行為一致),因此 import.meta.env.MISSING_KEY 與 const {FOO} = import.meta.env 這類解構在任何輸出格式下都是安全的。

執行階段的 import.meta.url

在 4.1.19 之前,打包工具會把 import.meta.url 替換成原始檔的 file:// 路徑。這個路徑會把建置機器上的資料夾名稱帶進發佈的 bundle。從 4.1.19 起,Extension.js 改為在執行階段解析裸的 import.meta.url,在 dev 與正式建置中都是如此,而且這個值永遠不會包含建置機器的路徑: 當你的程式碼透過 chrome.runtime.getURL、importScripts、executeScript({files}) 或根絕對路徑的 <script src> 載入一個模組時,這個模組就算是在執行階段被載入。在 4.1.21 之前,這樣的模組得到的是載入它的那個情境的值。 new URL("./image.png", import.meta.url) 仍然可用。打包工具會輸出該檔案,並讓 URL 指向輸出後的副本。在擴充功能程式碼中,import.meta.dirname 與 import.meta.filename 為 undefined,因為執行階段不存在檔案系統路徑。

擴充功能建置中的機密

瀏覽器擴充功能會在使用者的機器上執行。任何安裝你擴充功能的人,都可以檢視你打包進 JavaScript、HTML 或編譯後 manifest.json 的任何值。請把 bundle 視為公開內容。 幾條原則:
  • 絕對不要把 API 機密、簽章金鑰或驗證權杖放在 EXTENSION_PUBLIC_* 之後。這個前綴是為了標記「可安全發佈」,不是為了「隱藏」。
  • 機密值不要放進靜態 manifest.json、語系或 HTML 樣板中的 $EXTENSION_* 佔位符,因為它們會在建置時展開並寫進產物。
  • 任何特權操作都應交由你自己的後端處理,再從擴充功能在執行階段呼叫它。
  • 持續整合(CI)時,把建置機密放在 process.env(不要提交 env 檔),共用的安全預設值才用 .env.defaults。

最佳實務

  • 只暴露必須發佈的值: 只有對使用者端安全的鍵才以 EXTENSION_PUBLIC_ 為前綴。
  • 以 .env.defaults 提供共用預設: 保持團隊預設值可預期,同時允許本機/系統覆寫。
  • 機密不要放進靜態佔位符: 避免在 HTML/JSON 樣板中放入機密的 $EXTENSION_* 標記。
  • 版本控管乾淨: 提交 .env.example 作為文件(建置永遠不會把它當成值來源讀取),並忽略真正的 env 檔(.env、.env.local、瀏覽器/模式變體)。extension create 產生的 scaffold 已經這樣做了:它的 .gitignore 會忽略所有 .env* 檔案,再重新放行 .env.example、.env.*.example 以及模板本身附帶的 .env.<name> 檔案。

下一步

模板示範