# CLI 环境变量一览

> 本文整理 ArenaPro CLI 项目中常见的环境变量，说明它们的用途、在哪里配置，以及是否必需。

## 1. 地图与账号相关

> 用于「绑定哪张地图」「用哪个账号上传 / 拉取资源」。一般在 `.env` 中配置。

### 1.1 地图绑定 ID

- **`VITE_DAO3_MAP_ID`**
  - **用途**：当前工程要绑定 / 上传的地图 ID。
  - **配置位置**：通常通过 `apc set <ID>` 自动写入 `.env[.mode]`。
  - **是否必需**：
    - 需要上传脚本到某张地图时 **必需**；
    - 只在本地做纯脚本构建时可以不配。

### 1.2 登录信息（通常走全局登录）

> 说明：一般推荐使用 `apc login` 完成**全局登录**，此时项目里的 `.env` 可以不写登录信息。只有在你确实需要“覆盖全局登录”或在 CI 中单独配置账号时，才需要配置下面这些变量。

- **`VITE_DAO3_AUTH`**

  - **用途**：账号 Token，用于上传脚本、同步资源等需要鉴权的操作。
  - **配置位置**：
    - 本地：按需写入 `.env`（覆盖当前机器的全局登录）；
    - CI：GitHub Secrets（`VITE_DAO3_AUTH`）。
  - **是否必需**：
    - 本地：通常 **不必** 单独配置，全局登录即可；
    - CI：用于自动上传时 **推荐配置**，让流水线也能独立完成鉴权。

- **`VITE_DAO3_UA`**
  - **用途**：上传时携带的 UA 标识，用于区分来源（脚手架、本地工具等）。
  - **配置位置**：同上，`.env` 或 CI Secrets。
  - **是否必需**：
    - 本地：可选；
    - CI：推荐配置，便于后台识别“这是 CI 流水线发起的上传”。

### 1.3 地图元信息

- **`VITE_DAO3_PLAY_HASH`**
- **`VITE_DAO3_EDIT_HASH`**
- **`VITE_DAO3_MAP_NAME`**

说明：

- 这些字段通常由 `apc set` 自动写入 `.env`，来源于你通过 `apc list` 选中的那张地图；
- 主要用于 `apc preview` 打开创作 / 游玩链接，以及在日志中标注“当前绑定的地图名称”。
- **是否必需**：不直接影响构建，但推荐保留，方便预览和排查问题。

## 2. 构建行为控制

> 决定“构建哪一个 bundle”“构建结束要不要自动上传”。

- **`VITE_CURRENT_FILE`**

  - **用途**：当前要构建 / 上传的 bundle 名称（如 `bundle`、`bundle.pve` 等）。
  - **配置位置**：`.env`；通常由脚手架初始生成，也可以手动修改。
  - **是否必需**：
    - 对于使用官方脚手架的项目，**推荐必配**；
    - CLI 会根据这个字段和 `dao3.config.ts` 里定义的 bundle 做匹配。

- **`VITE_UPDATE_FILE`**
  - **用途**：控制构建完成后是否自动上传脚本到地图。
  - **典型值**：`"true"` / `"false"`（字符串）。
  - **配置位置**：
    - 本地 `.env`：默认可设为 `false`，只在手动需要时改为 `true`；
    - CI workflow：强烈推荐在 YAML 里 **显式覆盖**：
      - 构建检查流水线：`VITE_UPDATE_FILE: "false"`；
      - 发布流水线：`VITE_UPDATE_FILE: "true"`。
  - **是否必需**：
    - 不上传时可以不设，CLI 会当作 `false` 处理；
    - 建议始终显式设置，避免误上传。

## 3. CI / 发布相关

> 用于标记“是不是 CI 构建”“这是哪个版本”。

- **`VITE_CI`**

  - **用途**：标记这次构建 / 上传是否来自 CI 流水线。
  - 在 ArenaPro CLI 中的约定用法：
    - 当 `VITE_CI="true"` 时，CLI 会把这次构建视为 **CI 构建**；
    - 上传的脚本文件会使用带 `.ci.js` 等后缀的命名，方便区分是开发者本地上传，还是由流水线自动发布的版本。
  - **配置位置**：一般 **只在 CI workflow 中设置**：
    ```yaml
    env:
      VITE_CI: "true"
    ```
  - **是否必需**：
    - 本地开发不需要；
    - 在你想区分“CI 版本 / 本地版本”的项目里，推荐在发布流水线中设置。

- **`VITE_VERSION`**

  - **用途**：记录这次发布的版本号（通常直接来自 tag，如 `v1.2.3`）。
  - **配置位置**：发布流水线里解析 tag 并写入：

    ```yaml
    - name: 解析当前版本号
      run: |
        VERSION="${GITHUB_REF#refs/tags/}"
        echo "VERSION=$VERSION" >> $GITHUB_ENV

    - name: 构建并上传到神岛
      env:
        VITE_VERSION: ${{ env.VERSION }}
        VITE_UPDATE_FILE: "true"
        ...
    ```

  - **是否必需**：
    - 不是 CLI 强制要求；
    - 推荐在中大型项目里使用，用于在脚本中 `import.meta.env.VITE_VERSION` 打日志、回溯“是哪个版本出问题”。

## 4. Vite 内置与自定义变量

> 这些是 Vite 自带或常见约定，ArenaPro 项目中也会用到。

- **`import.meta.env.MODE`**

  - **用途**：当前运行模式（`development` / `production` 等）。
  - **配置位置**：Vite 自动注入；通过 `npm run dev` / `npm run build` 的 `--mode` 控制。
  - **是否必需**：不需要自己配置，按脚手架默认即可。

- **其他 `VITE_*` 自定义变量**
  - 你可以在 `.env` 中自行扩展，例如：
    - `VITE_FEATURE_FLAG_X=1`
    - `VITE_LOG_LEVEL=debug`
  - 只要以 `VITE_` 开头，就会被注入到 `import.meta.env` 中。
  - 建议： - 所有会下发到客户端的配置，都用 `VITE_` 前缀； - 新增时记得在 `env.d.ts` 里补类型声明。
    s
