环境变量配置

Plasmo 框架提供了完善的环境变量支持，使您能够使用同一套代码库为不同的浏览器和开发环境定制扩展行为。

示例项目

• with-env  - 环境变量使用示例

内置环境变量

Plasmo 框架自动提供以下内置环境变量：

• NODE_ENV: 根据构建命令自动设置为 development 或 production
• PLASMO_TARGET: 指定的构建目标，如 chrome-mv3，由 —target 标志 指定
• PLASMO_BROWSER: 目标浏览器名称，如 chrome、firefox 等
• PLASMO_MANIFEST_VERSION: 清单版本，如 mv3 或 mv2
• PLASMO_TAG: 构建标签，如 dev、prod 或由 —tag 标志 指定的自定义标签

自定义环境变量

要添加自定义环境变量，请创建 .env 文件：

PLASMO_PUBLIC_SHIP_NAME=ncc-1701
PLASMO_PUBLIC_SHIELD_FREQUENCY=42
 
PRIVATE_KEY=xxx # 此变量不会注入到客户端

环境文件优先级

开发/生产环境分离

要为开发和生产环境设置不同的变量，可以使用：

• .env.development - 开发环境专用
• .env.production - 生产环境专用

例如，如果 .env.development 中包含 CRX_PUBLIC_KEY 变量，但在 .env.production 或 .env 中没有，则该变量仅在 plasmo dev 时可用，在 plasmo build 时不可用。

特定构建环境

Plasmo 支持针对特定构建目标或构建标签的环境文件。例如执行以下命令时：

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

将按以下优先级顺序加载环境文件：

1. .env.safari - 浏览器特定配置
2. .env.alpha - 标签特定配置
3. .env - 通用配置

本地环境文件

Plasmo 还支持本地环境文件（Next.js 开发者会感到熟悉）：

• .env.<浏览器>.local
• .env.<标签>.local
• .env.<NODE_ENV>.local
• .env.local

以 .local 结尾的文件具有更高的优先级。例如，.env.local 的优先级高于 .env.production 和 .env.development。

环境文件的级联策略基于 dotenv 包 的实现。

最高优先级环境文件

要使用优先级最高的环境文件，可以使用 --env 标志指定任意文件：

plasmo build --env=.env.important

环境变量使用方式

在源代码中使用

在 TypeScript/JavaScript 代码中通过 process.env.<变量名> 访问：

// 在 React 组件中（弹出窗口、选项页面等）：
const FrontHull = () => <h1>{process.env.PLASMO_PUBLIC_SHIP_NAME}</h1>
 
// 在脚本文件中（内容脚本、后台脚本）：
const shield = new Shield(process.env.PLASMO_PUBLIC_SHIELD_FREQUENCY)
 
// 未以 PLASMO_PUBLIC_ 前缀的变量为 undefined
console.log(process.env.PRIVATE_KEY) // undefined

完整示例请参考 with-env 。

在远程代码导入中使用

在远程代码导入时使用环境变量：

import "https://www.plasmocn.org/js?id=$PLASMO_PUBLIC_ITERO"

在内容脚本配置中使用

在内容脚本配置中使用环境变量：

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

在清单配置中使用

在清单覆盖配置中使用环境变量：

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

在清单配置中既可以使用公共环境变量（PLASMO_PUBLIC_ 前缀），也可以使用私有环境变量。

最佳实践