环境变量配置指南

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

基础概念#

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

• 临时变量: 仅在创建它的终端会话中有效。关闭终端后即失效。
• 永久变量: 持久化存储在系统配置文件中，在新的终端会话或系统重启后依然有效。

macOS & Linux 配置说明#

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

了解 Shell 配置文件#

• ~/.bash_profile: Bash 登录 Shell 时加载。通常用于定义希望在整个用户会话期间都可用的变量。
• ~/.bashrc: Bash 交互式非登录 Shell 时加载。适合定义别名和函数。
• ~/.zshenv: (推荐用于环境变量) Zsh 每次启动时都会加载，无论是否是登录或交互式 Shell。这是设置环境变量最可靠的地方。
• ~/.zprofile: Zsh 登录 Shell 时加载，在 .zshenv 之后。
• ~/.zshrc: Zsh 交互式 Shell 时加载。适合配置 Shell 交互相关的设置（如提示符、别名）。

Bash / Zsh 配置#

临时配置#

在终端中执行 export 命令。

1
2# 示例：临时设置 ARK_API_KEY
export ARK_API_KEY="your-ark-api-key-here"

永久配置#

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

   Bash

   1
   2
   3
   4
   5echo $SHELL
   
   # 返回/bin/zsh：默认的 Shell 类型是 Zsh（ Z shell）。
   
   # 返回/bin/bash：默认的 Shell 类型是 Bash。
   

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

   Bash

   1
   2
   3
   4
   5# Zsh 用户
   nano ~/.zshenv
   
   # Bash 用户
   nano ~/.bash_profile
   

3. 在文件末尾添加 export 语句。

   Bash

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

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

   Bash

   1
   2
   3
   4
   5# Zsh 用户
   source ~/.zshenv
   
   # Bash 用户
   source ~/.bash_profile
   

PowerShell (macOS / Linux)#

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

临时配置#

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

永久配置#

1. 编辑 PowerShell 的配置文件。

   PowerShell

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

2. 在文件中添加以下行：

   PowerShell

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

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

   PowerShell

   1. $profile
   

#

Windows 配置说明#

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

Command Prompt (CMD)#

临时配置#

使用 set 命令。

1set ARK_API_KEY=your-ark-api-key-here

永久配置#

使用 setx 命令。

1
2
3
4
5:: 设置用户变量
setx ARK_API_KEY "your-ark-api-key-here"

:: 设置系统变量 (需要管理员权限)
setx ARK_API_KEY "your-ark-api-key-here" /m

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

PowerShell#

临时配置#

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

永久配置#

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

1
2
3
4
5# 设置用户变量
[Environment]::SetEnvironmentVariable("ARK_API_KEY", "your-ark-api-key-here", "User")

# 设置系统变量 (需要管理员权限)
[Environment]::SetEnvironmentVariable("ARK_API_KEY", "your-ark-api-key-here", "Machine")

图形用户界面 (GUI)#

1. 在开始菜单搜索“编辑系统环境变量”并打开。
2. 在“系统属性”对话框中，点击“环境变量...”按钮。
3. 在弹出的窗口中，您可以在上半部分为您的用户账户添加/修改“用户变量”，或在下半部分为所有用户添加/修改“系统变量”。
4. 点击“新建...”并输入变量名 ARK_API_KEY 和您的密钥作为变量值。
5. 逐层点击“确定”关闭所有对话框。

#

验证配置#

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

• macOS / Linux:

  Bash

  1echo $ARK_API_KEY
  

• Windows (CMD):

  Bash

  1echo %ARK_API_KEY%
  

• PowerShell (所有平台):

  PowerShell

  1
  2
  3echo $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 是一个强大的工具，它可以在您进入或离开项目目录时自动加载或卸载环境变量。

1. 安装 (以 macOS Homebrew 为例):

   Bash

   1brew install direnv
   

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

   Bash

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

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