文档中心

火山方舟

实践教程

环境变量配置指南

本文阐明如何在 macOS、Windows 和 Linux 系统中高效、正确地配置环境变量，避免在代码中明文写入 API Key、Access Key 等信息。

操作系统	Shell	临时设置 (当前会话)	永久设置 (推荐文件)
macOS / Linux	Bash / Zsh	export ARK_API_KEY="value"	~/.zshenv 或 ~/.bash_profile
	PowerShell	$env:ARK_API_KEY = "value"	Microsoft.PowerShell_profile.ps1
Windows	Command Prompt	set ARK_API_KEY=value	setx ARK_API_KEY "value"
	PowerShell	$env:ARK_API_KEY = "value"	[Environment]::SetEnvironmentVariable(...)

基础概念

环境变量是操作系统级的键值对，用于存储配置信息，能够影响运行中进程的行为。它们分为两类：

临时变量: 仅在创建它的终端会话中有效。关闭终端后即失效。

永久变量: 持久化存储在系统配置文件中，在新的终端会话或系统重启后依然有效。

macOS & Linux 配置说明

在类 Unix 系统中，环境变量的配置与您使用的 Shell 密切相关。

了解 Shell 配置文件

~/.bash_profile: Bash 登录 Shell 时加载。通常用于定义希望在整个用户会话期间都可用的变量。

~/.bashrc: Bash 交互式非登录 Shell 时加载。适合定义别名和函数。

~/.zshenv: (推荐用于环境变量) Zsh 每次启动时都会加载，无论是否是登录或交互式 Shell。这是设置环境变量最可靠的地方。

~/.zprofile: Zsh 登录 Shell 时加载，在 .zshenv 之后。

~/.zshrc: Zsh 交互式 Shell 时加载。适合配置 Shell 交互相关的设置（如提示符、别名）。

说明

为确保环境变量在所有场景下（包括 GUI 应用）都可用，建议将 export 语句放在 ~/.zshenv (Zsh) 或 ~/.bash_profile (Bash) 文件中。

Bash / Zsh 配置

临时配置

在终端中执行 export 命令。

永久配置

打开在终端，使用以下命令，查看默认 Shell 类型。

echo $SHELL

# 返回/bin/zsh：默认的 Shell 类型是 Zsh（ Z shell）。

# 返回/bin/bash：默认的 Shell 类型是 Bash。

打开您的 Shell 配置文件。对于 Zsh 用户，推荐 ~/.zshenv。

# Zsh 用户
nano ~/.zshenv

# Bash 用户
nano ~/.bash_profile

在文件末尾添加 export 语句。

# 设置 ARK_API_KEY 环境变量
export ARK_API_KEY="your-ark-api-key-here"

保存文件，然后运行 source 命令或重启终端使配置生效。

# Zsh 用户
source ~/.zshenv

# Bash 用户
source ~/.bash_profile

PowerShell (macOS / Linux)

PowerShell 在所有平台上的行为基本一致。

临时配置

永久配置

编辑 PowerShell 的配置文件。

# 这会自动用默认编辑器打开配置文件
code $profile

在文件中添加以下行：

$env:ARK_API_KEY = "your-ark-api-key-here"

保存文件，然后运行 . 命令或重启 PowerShell。

. $profile

Windows 配置说明

Windows 将环境变量分为“用户变量”和“系统变量”。前者仅对当前用户有效，后者对所有用户有效。

Command Prompt (CMD)

临时配置

使用 set 命令。

永久配置

使用 setx 命令。

注意: setx 设置的变量在新的命令提示符窗口中才会生效，不会影响当前窗口。

PowerShell

临时配置

永久配置

使用 .NET API 是最可靠的方式。

图形用户界面 (GUI)

在开始菜单搜索“编辑系统环境变量”并打开。

在“系统属性”对话框中，点击“环境变量...”按钮。

在弹出的窗口中，您可以在上半部分为您的用户账户添加/修改“用户变量”，或在下半部分为所有用户添加/修改“系统变量”。

点击“新建...”并输入变量名 ARK_API_KEY 和您的密钥作为变量值。

逐层点击“确定”关闭所有对话框。

验证配置

配置完成后，您可以通过以下方式验证：

macOS / Linux:

echo $ARK_API_KEY

Windows (CMD):

echo %ARK_API_KEY%

PowerShell (所有平台):

echo $env:ARK_API_KEY
# 或者
Get-ChildItem env:ARK_API_KEY

对于永久配置，请务必重启您的终端或 IDE 后再次检查，以确保配置已正确加载。

高级技巧与实践

安全性：保护您的密钥

警告: 绝对不要将包含 ARK_API_KEY 等敏感信息的配置文件提交到 Git 等版本控制系统。

使用 .gitignore: 确保包含敏感信息的本地配置文件（如 .envrc, .env）被添加到 .gitignore 文件中。

项目级环境变量: 对于特定项目，推荐使用 .env 文件来管理环境变量，并结合 dotenv (Node.js), python-dotenv (Python) 等库在应用启动时加载它们。

目录级环境变量 direnv

direnv 是一个强大的工具，它可以在您进入或离开项目目录时自动加载或卸载环境变量。

安装 (以 macOS Homebrew 为例):

brew install direnv

配置: 在项目根目录创建一个 .envrc 文件。

# .envrc
export ARK_API_KEY="your-project-specific-key"

授权: 首次进入目录时，运行 direnv allow。之后每次进入该目录，.envrc 中的变量都会自动生效。

最近更新时间：2026.10.13 14:33:22

这个页面对您有帮助吗？

有用

无用