# 环境变量配置指南

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

本文阐明如何在 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(...)` |

<span id="a145656a"></span>
## 基础概念

环境变量是操作系统级的键值对，用于存储配置信息，能够影响运行中进程的行为。它们分为两类：
* **临时变量**: 仅在创建它的终端会话中有效。关闭终端后即失效。
* **永久变量**: 持久化存储在系统配置文件中，在新的终端会话或系统重启后依然有效。

<span id="42cfcec5"></span>
## macOS & Linux 配置说明

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

<span id="2f4b1943"></span>
### 了解 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) 文件中。

<span id="a8329a39"></span>
### Bash / Zsh 配置

<span id="e9350dae"></span>
#### 临时配置

在终端中执行 `export` 命令。

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

<span id="37c37c61"></span>
#### 永久配置

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

    ```Bash
    echo $SHELL

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

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

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

    ```Bash
    # Zsh 用户
    nano ~/.zshenv

    # Bash 用户
    nano ~/.bash_profile
    ```

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

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

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

    ```Bash
    # Zsh 用户
    source ~/.zshenv

    # Bash 用户
    source ~/.bash_profile
    ```

<span id="a1ce8851"></span>
### PowerShell (macOS / Linux)

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

<span id="174ea7f4"></span>
#### 临时配置

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

<span id="bb5a3575"></span>
#### 永久配置

1. 编辑 PowerShell 的配置文件。

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

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

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

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

    ```PowerShell
    . $profile
    ```

<span id="871e9de7"></span>
##

<span id="e041d007"></span>
## Windows 配置说明

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

<span id="fc935d23"></span>
### Command Prompt (CMD)

<span id="4168a170"></span>
#### 临时配置

使用 `set` 命令。

```Bash
set ARK_API_KEY=your-ark-api-key-here
```

<span id="886575ad"></span>
#### 永久配置

使用 `setx` 命令。

```Bash
:: 设置用户变量
setx ARK_API_KEY "your-ark-api-key-here"

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

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

<span id="83f57ec4"></span>
### PowerShell

<span id="62cc96e9"></span>
#### 临时配置

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

<span id="4c7dda23"></span>
#### 永久配置

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

```PowerShell
# 设置用户变量
[Environment]::SetEnvironmentVariable("ARK_API_KEY", "your-ark-api-key-here", "User")

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

<span id="60200b14"></span>
### 图形用户界面 (GUI)

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

<span id="3dc63ba8"></span>
##

<span id="0b7661fa"></span>
## 验证配置

配置完成后，您可以通过以下方式验证：
* **macOS / Linux**:

    ```Bash
    echo $ARK_API_KEY
    ```

* **Windows (CMD)**:

    ```Bash
    echo %ARK_API_KEY%
    ```

* **PowerShell (所有平台)**:

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

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

<span id="5ac38111"></span>
##

<span id="4bc54785"></span>
## 高级技巧与实践

<span id="44b73a58"></span>
### 安全性：保护您的密钥

**警告**: 绝对不要将包含 `ARK_API_KEY` 等敏感信息的配置文件提交到 Git 等版本控制系统。
* **使用** **`.gitignore`**: 确保包含敏感信息的本地配置文件（如 `.envrc`, `.env`）被添加到 `.gitignore` 文件中。
* **项目级环境变量**: 对于特定项目，推荐使用 `.env` 文件来管理环境变量，并结合 `dotenv` (Node.js), `python-dotenv` (Python) 等库在应用启动时加载它们。

<span id="f073edb7"></span>
### 目录级环境变量 `direnv`

`direnv` 是一个强大的工具，它可以在您进入或离开项目目录时自动加载或卸载环境变量。
1. **安装** (以 macOS Homebrew 为例):

    ```Bash
    brew install direnv
    ```

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

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

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