跳到主要内容

环境变量

ice.js 内置通过环境变量实现给构建或运行时传递参数的功能。

  • 使用 .env 文件来配置环境变量
  • 配置 ICE_ 开头的环境变量则会同时暴露到运行时环境中

如何配置环境变量

命令行环境变量

例如需要修改 ice.js 本地开发服务的端口号,可以在命令行中使用环境变量:

$ cross-env PORT=9999 npm start

示例中使用了 cross-env 来兼容不容操作系统的环境变量配置方式。

使用 .env 文件

ice.js 内置了加载 .env 文件的支持,在该文件中设置的环境变量会被自动加载到 process.env 上。

.env 文件的示例:

DEV_PORT=3000
FOO=bar

如果有部分环境变量的配置在本地有差异,你可以配置在 .env.local 文件中去覆盖 .env 中的配置。如在之前的 .env 的基础上, 你想本地开发覆盖之前 3000 端口, 而使用 9999 端口,示例如下:

# The .env.local should not be committed.
DEV_PORT=9999

此外你也可以在 .env.${mode}.env.${mode}.local 文件中指定不同模式下的环境变量。${mode} 的取值是 developmentproduction

需要注意的是:

  1. 这几个文件的优先级由低至高分别是
  • .env
  • .env.local
  • .env.${mode}
  • .env.${mode}.local
  1. 一般不建议将 .local 结尾的文件加入版本管理 (如 Git) 中。

使用环境变量

在 ice.js 中,环境变量的使用场景分构建时与运行时两种类型。

特别注意:环境变量在使用时的类型都是 string,特别是设置为 truefalse 时需要注意判断为字符串类型:

// ICE_DISABLE_FOO=false
if (process.env.ICE_DISABLE_FOO === 'false') {
// ...
}

构建时

默认情况下,所有设置的环境变量都会被注入到构建环境,你可以在 ice.config.mts 文件或其它构建插件中通过 process.env 变量访问。

const port = process.env.PORT;
// ...

运行时

默认情况下环境变量是不能在运行时访问的,如若需要在浏览器环境中访问,可以在设置环境变量时增加前缀:ICE_,如:

# File .env
ICE_APP_ID=123456

在运行时代码中访问:

import React from 'react';

export default function AppID() {
return <h1>AppId is {process.env.ICE_APP_ID}.</h1>
}

内置的环境变量

ice.js 会内置一些环境变量方便使用,通常由 ICE_CORE_ 开头,如下:

ICE_CORE_MODE

用于 ice.js 的运行模式,可能是 developmentproduction

ICE_CORE_ROUTER

用于标识框架是否启用路由,可能是 truefalse

ICE_CORE_ERROR_BOUNDARY

用于标识框架是否启用错误边界,可能是 truefalse

ICE_CORE_INITIAL_DATA

用于标识框架是否启用初始数据,可能是 truefalse

ICE_CORE_DEV_PORT

用于标识 ice.js 的开发服务器端口号。