---
url: /zh/workspaces/personal-envs.md
description: >
  介绍云原生开发的「个人环境变量」用法：以个人维度配置密钥文件 imports， 通过 use_in_slugs 仓库白名单控制可注入范围，复用
  imports 的拉取与鉴权机制， 实现跨仓库的个人开发密钥安全共享。
---
`个人环境变量`是用户维度的配置，可在启动`云原生开发`环境时，
把你指定的密钥文件自动注入为环境变量。

与在 `.cnb.yml` 按仓库配置 [imports](../build/grammar.md#pipeline-imports) 不同，
个人环境变量在你个人维度生效，通过 `use_in_slugs` 仓库白名单控制可注入范围，
适用于跨多个仓库复用同一份个人开发密钥的场景。

::: tip
个人环境变量仅在`云原生开发`环境中生效，不影响普通构建（`Build`）。
:::

## 配置入口

在 [个人设置 > 云原生开发](https://cnb.cool/profile/workspaces) 页面，
找到`个人环境变量`，按 YAML 格式填写并保存。

## 格式说明

配置内容为 YAML 数组，每项包含两个字段（`imports` 用法同流水线
[imports](../build/grammar.md#pipeline-imports)）：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `imports` | `String` | `Array<String>` | 是 | 密钥文件地址 |
| `use_in_slugs` | `String` | `Array<String>` | 是 | 允许注入这些密钥的仓库，支持 Glob |

::: warning use\_in\_slugs 必填
若某项未配置 `use_in_slugs`，或当前开发环境所在仓库不命中其中任何一条，
该项**不会被注入**，避免个人密钥泄漏到不信任的仓库。
:::

**示例：**

```yaml
- imports: https://cnb.cool/<your-secret-repo-slug>/-/blob/main/npm.yml
  use_in_slugs:
    - your-group/**
- imports:
    - https://cnb.cool/<your-secret-repo-slug>/-/blob/main/docker.yml
    - https://cnb.cool/<your-secret-repo-slug>/-/blob/main/k8s.yml
  use_in_slugs:
    - your-group/project-a
    - your-group/project-b
```

上面示例：

* 第一项的 `npm.yml` 会在 `your-group/` 下所有仓库的开发环境中注入；
* 第二项的 `docker.yml`、`k8s.yml` 仅在 `your-group/project-a` 和
  `your-group/project-b` 的开发环境中注入。

## 生效范围与优先级

* **生效范围**：仅对当前用户启动的`云原生开发`环境生效。
* **优先级**：个人环境变量在仓库流水线 `imports` 之后注入，
  因此当变量同名时，**个人环境变量会覆盖**仓库 `imports` 中的同名变量。
  `.cnb.yml` 中显式声明的 `env` 仍然优先级最高。

## 安全与鉴权

个人环境变量完整复用 [imports](../build/grammar.md#pipeline-imports) 的鉴权链路，
注入前必须**同时满足**以下条件：

1. **注入白名单**：当前仓库命中该项的 `use_in_slugs`（个人维度的注入目标控制）；
2. **引用鉴权**：注入前会校验当前开发环境所在仓库是否允许读取该密钥文件，
   规则同流水线 [imports](../build/grammar.md#pipeline-imports)：

   * 密钥文件就放在当前仓库下，或所在仓库是公开仓库 —— 直接通过；
   * 跨仓库引用，且密钥文件的**内容**中声明了 `allow_slugs` 等字段
     （在 yml/json 文件内写明允许引用它的仓库范围）—— 按这些声明校验；
   * 跨仓库引用，且密钥文件的内容**未**声明任何 `allow_*` ——
     要求你本人对密钥文件所在仓库有读取（pull）权限。

   完整规则详见 [配置文件引用鉴权](../build/file-reference.md#权限检查)。

::: tip
推荐将密钥文件放在专门的 [密钥仓库](../repo/secret.md)，安全性更高且支持引用审计。
密钥文件的格式与解析规则同流水线 imports，
详见 [文件解析规则](../build/grammar.md#文件解析规则)。
:::

## 注意事项

* 配置内容总长度受限（当前 2000 字符以内），请勿存放过长内容；
* `imports` 仅支持 CNB 站内文件地址，或相对路径
  （相对路径会被解析为当前启动开发环境所在仓库下的文件，例如 `./.cnb/env.yml`）；
  外部地址不会被加载；
* 非法项（如 yml 格式错误、缺少 `use_in_slugs`）会被忽略，不影响开发环境正常启动；
* 但**密钥文件地址必须可访问**：路径错误、文件不存在或鉴权不通过
  都会导致开发环境**启动失败**。

## 安全注意事项

::: warning 个人环境变量会作为环境变量注入开发环境，在容器内可被任意脚本读取（如 `env`、`echo $XXX`），建议

* **只注入你信任的组织或仓库**：`use_in_slugs` 务必精确到你信任的组织或具体仓库，
  **避免 `**` 这类大通配**；若注入到不信任的仓库，存在密钥被窃取的风险——
  例如这些仓库的写权限者可在 `.cnb.yml` 中以多种方式
  （如 `curl` 外发、打印到构建日志等）将你注入的环境变量窃取出去；
* **密钥文件放[密钥仓库](../repo/secret.md)**，**不要放公开仓库**；
  若密钥文件内配置了 `allow_slugs`，注意它表示"允许这些仓库引用本文件"，
  配置过宽（如 `**`）会导致他人也能引用你的密钥文件，应尽量收敛；
  若文件仅供你自己用，可不写 `allow_slugs`，由 pull 权限把关。

:::