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 中设置：

    env:
      VITE_CI: "true"

  • 是否必需：
    • 本地开发不需要；
    • 在你想区分“CI 版本 / 本地版本”的项目里，推荐在发布流水线中设置。

• VITE_VERSION

  • 用途：记录这次发布的版本号（通常直接来自 tag，如 v1.2.3）。

  • 配置位置：发布流水线里解析 tag 并写入：

    - 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