环境变量

Plasmo 提供了对环境变量的一流支持。这使您可以根据每个浏览器和开发环境的需求自定义扩展程序，同时使用相同的代码库。

示例

• with-env (opens in a new tab)

内置环境变量

Plasmo 框架提供了以下内置客户端环境变量：

• NODE_ENV: 根据构建命令为 development 或 production
• PLASMO_TARGET: 由 the --target flag 指定的目标，例如 chrome-mv3
• PLASMO_BROWSER: 目标浏览器的名称，例如 chrome
• PLASMO_MANIFEST_VERSION: 清单版本，例如 mv3 或 mv2
• PLASMO_TAG: 构建标签，例如 dev、prod 或通过 the --tag flag 指定的自定义标签

自定义环境变量

要添加扩展程序可访问的环境变量，请创建一个 .env 文件：

PLASMO_PUBLIC_SHIP_NAME=ncc-1701
PLASMO_PUBLIC_SHIELD_FREQUENCY=42
 
PRIVATE_KEY=xxx # 在扩展程序中未定义

NODE_ENV 特定环境

为了在 dev 和 build 之间分离环境变量，可以使用以下文件：

• .env.development
• .env.production

如果 .env.development 中有一个 CRX_PUBLIC_KEY 环境变量，但在 .env.production 或 .env 中没有，则它仅在 plasmo dev 中可用，而不是在 plasmo build 中。

Bundle 特定环境

当创建最终包时，Plasmo 框架还提供特定于某些 build target 或 build tag 的环境变量。给定以下构建命令：

plasmo build --target=safari-mv3 --tag=alpha

将按优先级顺序考虑以下 env 文件：

• .env.safari
• .env.alpha
• .env

本地环境

Plasmo 还支持以下环境文件名（Next.js 开发者会发现这些很熟悉）：

• .env.<browser>.local
• .env.<tag>.local
• .env.<NODE_ENV>.local
• .env.local

以 .local 结尾的文件优先级高于非本地文件。例如，.env.local 的优先级高于 .env.production 和 .env.development。

在同一命名空间内，级联顺序如预期一样。此功能利用了使用 dotenv 包 (opens in a new tab) 的环境变量级联/覆盖策略。

优先级环境

要包含优先级高于所有其他环境文件的环境文件，请使用 --env 标志。此文件的名称可以是任意名称：

plasmo build --env=.env.important

使用环境变量

环境变量是一个强大的功能，允许您根据每个浏览器和开发环境的需求自定义扩展程序，同时使用相同的代码库。

在源代码中

要在源代码中引用环境变量，请使用完整路径 process.env.<ENV_NAME>。例如：

// 对于 TSX (弹出窗口、选项页面):
const FrontHull = () => <h1>{process.env.PLASMO_PUBLIC_SHIP_NAME}</h1>
 
// 对于 TS (内容脚本或后台脚本):
const shield = new Shield(process.env.PLASMO_PUBLIC_SHIELD_FREQUENCY)
 
// 将为 undefined，因为它没有以 PLASMO_PUBLIC_ 开头
console.log(process.env.PRIVATE_KEY)

有关使用 .env 变量的更多详细信息，请参阅 with-env (opens in a new tab)。

在远程代码导入中

如果您正在 导入远程代码，请使用公共环境变量：

import "https://www.plasmo.com/js?id=$PLASMO_PUBLIC_ITERO"

在内容脚本配置中

您还可以在 内容脚本配置导出 中使用环境变量：

export const config: PlasmoCSConfig = {
  matches: ["$PLASMO_PUBLIC_SITE_URL/"]
}

在清单覆盖中

Plasmo 允许您通过 package.json 文件中的 manifest 属性 覆盖最终生成的扩展程序清单。更进一步，Plasmo 还解析清单覆盖中使用的任何环境变量：

"manifest": {
  "key": "$CRX_PUBLIC_KEY"
}

您可以在清单覆盖中使用公共（以 PLASMO_PUBLIC 开头）和私有环境变量。 😎