# 环境变量
<subtitle>在沙箱内读取默认环境变量，并按全局、代码执行或命令执行粒度注入自定义变量。</subtitle>

环境变量可以帮助您把运行上下文传递给沙箱内的程序，例如业务模式、外部服务地址、调试开关或一次性参数。UCloud Sandbox 会自动注入部分默认变量，也支持在创建沙箱和执行任务时注入自定义变量。

## 默认环境变量

沙箱启动后，系统会为命令执行环境注入以下默认变量：

- `UCLOUD_SANDBOX`：固定为 `true`，用于判断当前进程是否运行在 UCloud Sandbox 内。
- `UCLOUD_SANDBOX_ID`：当前沙箱 ID。
- `UCLOUD_SANDBOX_TEMPLATE_ID`：当前沙箱使用的模板 ID。

可以在沙箱内通过命令读取这些变量：

```python
from ucloud_sandbox import Sandbox

sandbox = Sandbox.create()
result = sandbox.commands.run("echo $UCLOUD_SANDBOX_ID")
print(result.stdout)
```

如果通过 CLI 手动进入沙箱，默认变量也会以点文件形式保存在 `/run/ucloud/` 目录下：

```bash
user@ucloud:~$ ls -a /run/ucloud/
.  ..  .UCLOUD_SANDBOX  .UCLOUD_SANDBOX_ID  .UCLOUD_TEMPLATE_ID
```

> `/run/ucloud/` 下的点文件用于 CLI 会话中读取系统注入信息；SDK 命令执行中可直接读取对应环境变量。其中模板 ID 在 CLI 点文件中是 `.UCLOUD_TEMPLATE_ID`，在命令环境变量中是 `UCLOUD_SANDBOX_TEMPLATE_ID`。

## 设置环境变量

在沙箱中设置环境变量主要有三种方式：

1. 创建沙箱时设置全局环境变量。
2. 执行代码时临时设置环境变量。
3. 执行命令时临时设置环境变量。

### 1. 创建沙箱时设置全局环境变量

创建沙箱时传入 `envs`，这些变量会对该沙箱后续运行的进程可见。

```python
from ucloud_sandbox import Sandbox

sandbox = Sandbox.create(
    envs={
        "MY_VAR": "my_value",
        "APP_MODE": "production",
    },
)

result = sandbox.commands.run("echo $MY_VAR")
print(result.stdout)
```

### 2. 执行代码时临时设置环境变量

可以在某一次代码执行调用中传入 `envs`。这些变量只对本次执行生效。

> 这类环境变量的作用域仅限本次执行，但它们并不是操作系统层面的私密存储。如果同名变量已在全局环境中存在，本次执行传入的值会覆盖全局值。

```python
from ucloud_sandbox.code_interpreter import Sandbox

sandbox = Sandbox.create()

result = sandbox.run_code(
    'import os; print(os.environ.get("MY_VAR"))',
    envs={
        "MY_VAR": "my_value",
    },
)

print(result.logs.stdout)
```

### 3. 执行命令时临时设置环境变量

也可以在某一次 `commands.run()` 调用中传入 `envs`。这些变量只对本次命令执行生效。

> 如果同名变量同时存在于全局环境变量和本次命令的 `envs` 中，本次命令传入的值优先。

```python
from ucloud_sandbox import Sandbox

sandbox = Sandbox.create()

result = sandbox.commands.run(
    "echo $MY_VAR",
    envs={
        "MY_VAR": "123",
    },
)

print(result.stdout)
```

## 使用建议

- 用默认变量识别当前沙箱和模板，例如日志打点、回调上报或链路追踪。
- 用创建时的 `envs` 放置沙箱生命周期内都需要的配置。
- 用单次执行的 `envs` 传递临时参数，避免污染后续命令。
- 不建议通过环境变量长期保存敏感凭据；如果必须传入密钥，请控制沙箱内可访问它的进程范围，并在任务结束后及时销毁沙箱。