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

EXTENSION_PUBLIC_* 值)實際看看環境變數如何運作。
content-env

運作方式
擴充功能 bundle(編譯時)
建置擴充功能時,編譯器會讀取你的擴充功能套件資料夾中符合瀏覽器與模式的 env 檔。從 4.1.41 之後的版本起,它會讀取每一個符合的檔案,較強的檔案逐鍵覆寫較弱的檔案。較早的版本只讀取最強的那一個符合檔案。由強到弱:.env.[browser].[mode](例如.env.chrome.development).env.[browser]- 上述兩項的引擎家族變體(見下方說明)
.env.[mode].local(從 4.1.41 之後的版本起).env.[mode].env.local.env
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 僅作為文件範例,永遠不會被當成值來源載入。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。
.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_PUBLIC_ 前綴的變數注入 JS bundle。不過,輸出的
.json/.html 檔中的佔位符可以解析 $EXTENSION_* 標記,所以請避免在靜態資產樣板中引用機密。
使用環境變數
你可以在manifest.json、語系檔、HTML 與 JavaScript/TypeScript 檔案中使用環境變數。
1. 在 manifest.json 中
manifest.json 本身不支援環境變數,但 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_PUBLIC_SITE_URL 等佔位符替換為解析後的值。
從 4.2.0 之後的版本開始,_locales/<locale>/messages.json 中緊接著第二個 $ 的記號,比如 $EXTENSION_MODE$,是瀏覽器自己的訊息佔位符,所以建置會保持原樣。
3. 在 HTML 檔中
你也可以在靜態 HTML 檔中使用佔位符(例如放在pages/ 下):
$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 值:
process.env.EXTENSION_PUBLIC_X = "v" 這樣的寫入仍是有效程式碼,並在執行時寫到 env 物件上。對你自己的程式碼,建置會以 W_ENV_DEFINE_WRITTEN 警告,因為這個名稱的每一處點號讀取都保留建置時的值。執行時會變化的值請放進你自己的變數。
import.meta 支援
針對 ECMAScript Module(ESM)工作流程,Extension.js 也支援 import.meta.env:
service_worker.mjs
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>檔案。
下一步
- 在 可用的瀏覽器 檢視瀏覽器目標。
- 在
extension.config.js設定共用預設值。 - 用
extension build為發佈而建置。

