跳转到主要内容
让同一个扩展代码库在不同浏览器与环境间运行,而不必硬编码任何值。

浏览器扩展中的环境变量

浏览器扩展会发布到用户机器上运行。这让配置与密钥之间的界线比普通 Web 应用更加严格。任何安装你扩展的人都能读取你打进 JavaScript、HTML 或编译后的 manifest.json 中的所有内容。 Extension.js 通过两种环境加载路径来处理这件事。一种用于编译后的扩展产物(感知浏览器与模式)。另一种用于在 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

工作原理

扩展产物(编译时)

构建扩展时,编译器会读取扩展包目录中与浏览器和模式匹配的 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_ 前缀的名字,这样产物里永远不会包含它。 当某个带值的 EXTENSION_PUBLIC_* 变量的名字看起来像密钥时,生产构建会发出警告。名字包含 SECRET、TOKEN、PASSWORD 或 PRIVATE 时看起来像密钥。KEY 紧跟在 API、ACCESS、AUTH 或 SECRET 之后时也是。包含 PUBLISHABLE 的名字会被跳过。如果这个值本来就设计为公开的,比如 Firebase 的 web API key,这条警告对它并不适用。这条警告需要 4.1.39 或更高版本。 如果项目旁找不到匹配文件,Extension.js 会从最近的 workspace 根目录重复同样的搜索。所谓 workspace 根目录,是离当前位置最近、包含 pnpm-workspace.yaml 的祖先目录。位于 monorepo 中的扩展可以共享根级 env 文件来注入产物。只有 .env.defaults 这一个 env 文件的包,也会取用根目录的文件。根目录的 .env.defaults 先加载,包自己的 .env.defaults 按键胜出。 Monorepo 约束: 仅当祖先目录中存在 pnpm-workspace.yaml 这个标记文件时,workspace 回退才会执行。如果你使用的是仅依赖 package.json "workspaces" 字段的纯 npm 或 Yarn 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。这样配置看到的值与产物相同。4.2.0 及更早的版本在知道浏览器之前就加载 dev 的配置,所以 dev 不读取任何浏览器文件。从 4.2.0 之后的版本起,dev 在第一次加载配置时就读取浏览器的文件,比如 .env.chrome 与 .env.chrome.development。 从 4.1.41 之后的版本起,extension.config.js 每个命令只运行一次。当配置自己指定浏览器时,它可能再运行一次。只有当浏览器的文件改变了它读取过的某个变量时才会这样。 你也可以依赖编译期的产物 env(上文已说明) 将 EXTENSION_PUBLIC_* 注入扩展代码。 Workspace 回退: 如果扩展包目录中找不到上述任何文件,则会在最近的、包含 pnpm-workspace.yaml 的目录中执行同样的预加载(约束与上文一致)。 从 4.1.41 之后的版本起,只有 .env.defaults 这一个 env 文件的包也会以同样方式回退。根目录的 .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 之后的版本起,每个浏览器都按同一个顺序解析二进制。先是二进制 flag,然后是变量、受管理的二进制,最后是系统安装。变量指向不存在或不可执行的路径时,启动会以 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 容器或调试不稳定的浏览器连接很有用。

浏览器特定的环境变量

以下规则适用于编译期/产物 env 选择(见上文扩展产物)。它们不适用于 Node 中针对 extension.config.* 的窄范围预加载。 需要为每个浏览器使用不同的值吗?Extension.js 支持浏览器作用域的 env 文件,比如 .env.chrome(Chrome 扩展环境变量) 与 .env.firefox(Firefox 扩展环境变量)。你也可以把浏览器和模式组合起来,针对单个构建变体:
  • .env.chrome.development:只有在以开发模式运行 Chrome 时,Extension.js 才应用它。
  • .env.firefox.production:只有在以生产模式构建 Firefox 时,Extension.js 才应用它。
优先级顺序:
  • .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 产物(process.env / import.meta.env)。
重要: Extension.js 不会把没有 EXTENSION_PUBLIC_ 前缀的变量注入 JS 产物。
但输出的 .json / .html 文件中的占位符可以解析 $EXTENSION_* 标记,所以不要在静态资产模板里引用密钥。

使用环境变量

你可以在 manifest.json、locale 文件、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. 在 locale 文件中

当值应当随环境而变时,也可以在 locale 文件中使用占位符。例如:
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.2.0 之后的版本起,内联 <script> 中没有放在引号里的占位符会按原样取值,所以这个值本身必须是 JavaScript。填入值之后脚本不再能解析时,构建会以 E_INLINE_SCRIPT_SYNTAX 失败,消息会给出文件和占位符。给占位符加上引号,比如 "$EXTENSION_PUBLIC_API_URL",就能得到字符串。

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 中的任意值。请把扩展包视为公开内容。 几条规则要遵守:
  • 永远不要把 API 密钥、签名密钥或鉴权令牌放在 EXTENSION_PUBLIC_* 后面。这个前缀意味着该值可以安全发布,而不是用来隐藏它。
  • 不要在静态 manifest.json、locale 或 HTML 模板中放敏感值对应的 $EXTENSION_* 占位符。它们会在构建期展开,最终出现在产物里。
  • 把任何特权操作放到你自己的后端,扩展在运行时再调用它。
  • 对于持续集成 (CI),把构建期密钥放在 process.env(不要提交 env 文件),并把可共享的安全默认值放在 .env.defaults。

最佳实践

  • 只暴露必须发布的值: 只给客户端安全的键加 EXTENSION_PUBLIC_ 前缀。
  • 用 .env.defaults 共享团队默认值: 在保留可预测默认值的同时,允许本地/系统覆盖。
  • 不要把密钥放进静态占位符: 避免在 HTML/JSON 模板里放敏感的 $EXTENSION_* 标记。
  • 版本控制卫生: 提交 .env.example 作为文档(构建永远不会把它作为值来源读取),并忽略真实的 env 文件(.env、.env.local、浏览器/模式变体)。extension create 生成的脚手架已经这样做了:它的 .gitignore 会忽略所有 .env* 文件,再重新放行 .env.example、.env.*.example 以及模板自身附带的 .env.<name> 文件。

下一步

模板演示