EdgeOne Makers 构建与环境变量

上一篇讲了 Git 集成和自动部署的基本机制（EdgeOne Makers 部署基础），但实际开发中，项目往往不是简单的一键构建就完事。你可能需要在构建时注入一些配置信息，比如 API 地址、第三方服务的密钥等。这些配置不能写死在代码里，一方面是不灵活，另一方面是会有安全风险。这时候就需要用到环境变量。

构建配置详解

构建命令

构建命令就是告诉平台怎么把你的源码变成可部署的产物。

最常见的构建命令是 npm run build，这是大部分前端框架的标准命令。但有些项目可能有特殊的构建需求。

比如你的项目有两个构建脚本:

{
  "scripts": {
    "build": "vite build",
    "build:staging": "vite build --mode staging",
    "build:production": "vite build --mode production"
  }
}

你可以在项目设置里指定用哪个命令。比如测试环境用 npm run build:staging，生产环境用 npm run build:production。

输出目录

构建命令执行完后，产物会放在一个目录里。常见的输出目录有:

框架	默认输出目录
Vue + Vite	dist
React + Vite	dist
React + CRA	build
Next.js (静态导出)	out
Nuxt (静态导出)	dist
Hexo	public

平台会自动检测，但如果检测错了，可以在设置里手动改。

安装命令

安装依赖的命令，默认是 npm install。

如果你的项目用的是 pnpm 或者 yarn，可以在设置里改成:

pnpm install

或者:

yarn install

注意: 如果用 pnpm，平台会自动检测项目根目录有没有 pnpm-lock.yaml 文件，有就用 pnpm 安装。

Node 版本

默认用 Node 18.x，但如果你的项目需要特定版本，可以在项目根目录创建 .nvmrc 文件:

或者 .node-version 文件:

平台会读取这些文件，用对应的 Node 版本来构建。

支持的 Node 版本:

版本	说明
16.x	已停止维护，不建议使用
18.x	当前 LTS 版本，推荐使用
20.x	最新 LTS 版本，推荐新项目使用
22.x	最新版，可能有兼容性问题

环境变量管理

环境变量是存储在平台上的键值对，不会写进代码里，但在构建和运行时可以被读取。

添加环境变量

进入项目设置，点击”环境变量”标签，点击”添加环境变量”按钮。

填写变量名和变量值，比如:

变量名: API_BASE_URL
变量值: https://api.example.com

保存后，这个环境变量就配置好了。

读取环境变量

不同环境下读取环境变量的方式不一样。

前端项目

前端项目构建时，环境变量会被注入到代码里。

Vue 项目:

const apiUrl = import.meta.env.VITE_API_BASE_URL

注意: Vue + Vite 要求环境变量必须以 VITE_ 开头才能在前端代码中访问。

React + Vite 项目:

const apiUrl = import.meta.env.VITE_API_BASE_URL

React + CRA 项目:

const apiUrl = process.env.REACT_APP_API_BASE_URL

要求环境变量以 REACT_APP_ 开头。

后端项目

Node.js 后端项目:

const apiKey = process.env.API_KEY

Python 后端项目:

import os
api_key = os.getenv('API_KEY')

构建时环境变量 vs 运行时环境变量

对比维度	构建时环境变量	运行时环境变量
注入时机	执行构建命令时	每次请求时
前端可用	是，会被打包到产物里	否，前端拿不到
后端可用	是	是
修改后需要重新部署	是	否，立即生效
典型用途	API 地址、公开配置	数据库连接信息、密钥

添加环境变量时，平台会让你选择这个变量是构建时可用还是运行时可用，或者两者都是。

敏感信息安全

有些环境变量是敏感信息，比如数据库密码、API 密钥、第三方服务的 Token 等。

这些变量一定要设置成”运行时环境变量”，不能设置成”构建时环境变量”。

原因是构建时环境变量会被打包到前端代码里，任何人都能在浏览器里看到。运行时环境变量只存在于服务器端，前端代码访问不到。

加密环境变量

对于特别敏感的信息，平台提供了加密环境变量的功能。

添加环境变量时，勾选”加密”选项。加密后的变量值在控制台上不会明文显示，只能看到 ******。

即使有权限查看项目设置的人，也看不到具体的值，只能修改或删除。

环境变量最佳实践

实践	说明
不要硬编码	敏感信息不要写在代码里，用环境变量
区分环境	测试环境和生产环境用不同的变量值
最小权限	只给需要的变量，不要把所有配置都塞进去
定期轮转	密钥定期更换，降低泄露风险
使用加密	敏感变量勾选加密选项
不要提交到 Git	.env 文件加到 .gitignore 里

不同环境使用不同配置

一个项目通常有多个环境，比如开发环境、测试环境、生产环境。

不同环境的环境变量值可能不一样。

方法一: 在平台配置多套环境变量

EdgeOne Makers 支持按分支或部署类型区分环境变量。

比如:

main 分支的部署用生产环境的配置
develop 分支的部署用测试环境的配置

在添加环境变量时，可以选择这个变量只对哪个分支生效。

方法二: 在代码里根据环境判断

const env = process.env.NODE_ENV

let apiUrl
if (env === 'production') {
  apiUrl = 'https://api.production.com'
} else {
  apiUrl = 'https://api.staging.com'
}

这种方式不如方法一灵活，但也能用。

环境变量的作用域

环境变量可以在项目级别设置，也可以在团队级别设置。

作用域	说明	适用场景
项目级别	只对当前项目生效	项目特有的配置
团队级别	对团队下所有项目生效	通用的配置，比如公司统一的 API 地址

团队级别的环境变量会继承到所有项目，项目级别的环境变量会覆盖同名的团队级别变量。

速查卡片

要点	说明
构建命令	默认 npm run build，可以在设置里改
输出目录	平台自动检测，Vue 是 dist，React CRA 是 build
Node 版本	通过 .nvmrc 或 .node-version 文件指定
环境变量类型	构建时环境变量和运行时环境变量
前端读取方式	Vue 用 import.meta.env.VITE_XXX，React CRA 用 process.env.REACT_APP_XXX
后端读取方式	Node.js 用 process.env，Python 用 os.getenv
敏感信息	必须设置成运行时环境变量，不要设成构建时
加密环境变量	勾选加密选项，控制台不显示明文

EdgeOne Makers 部署基础

EdgeOne Makers 前端框架部署