vtj/docs/llms/env.md

VTJ 环境变量 — AI 配置与使用指南

本文档帮助 AI 理解如何通过工具方法配置环境变量，以及在组件中读取环境变量。

---

一、数据流全貌

设计器 env 面板                   项目数据                       渲染引擎
env/index.vue  ──setEnv()──▶  project.env  ──initEnv()──▶  provider.env
  (表格编辑)                     (EnvConfig[])  (按当前环境平铺)   (Record<string, string>)
                                                                  │
                                                  组件中: __provider.env.VAR_NAME

关键机制：

1. 双环境值存储： 每条环境变量同时配置 development（开发）和 production（生产）两个值
2. 运行时切换： initEnv() 根据当前 nodeEnv 自动选取对应的值，平铺为 { VAR_NAME: value } 对象
3. 全局可访问： provider.env 挂载在 Provider 实例上，组件通过 __provider.env.VAR_NAME 读取

---

二、EnvConfig 数据结构

字段	类型	必填	说明
name	string	✅	变量名，通常大写+下划线，如 BASE_URL、API_KEY
development	string	✅	开发环境下的值
production	string	✅	生产环境下的值

示例数据：

[
  {
    "name": "BASE_URL",
    "development": "http://localhost:8080",
    "production": "https://api.example.com"
  },
  { "name": "APP_TITLE", "development": "VTJ 开发版", "production": "VTJ" },
  {
    "name": "API_KEY",
    "development": "dev-key-123",
    "production": "prod-key-456"
  }
]

运行时（开发环境）__provider.env 的实际值：

{
  BASE_URL: 'http://localhost:8080',
  APP_TITLE: 'VTJ 开发版',
  API_KEY: 'dev-key-123'
}

---

三、环境变量工具方法

getEnv — 获取所有环境变量

获取当前项目配置的全部环境变量列表（包含两套值）。

参数： 无

返回： EnvConfig[] 数组，每项包含 name、development、production

---

createEnv — 新增环境变量

新增一条环境变量。如果 name 已存在则追加（同名可重复）。

参数：

参数	类型	必填	说明
config.name	string	✅	变量名，推荐大写+下划线，如 BASE_URL
config.development	string	✅	开发环境的值
config.production	string	✅	生产环境的值

示例：

{
  "action": "createEnv",
  "parameters": [
    {
      "name": "BASE_URL",
      "development": "http://localhost:8080/api",
      "production": "https://api.example.com"
    }
  ]
}

---

removeEnv — 删除环境变量

根据变量名 name 删除环境变量。如果存在多个同名变量，同时全部删除。

参数：

• name: string — 变量名称

示例：

{
  "action": "removeEnv",
  "parameters": ["BASE_URL"]
}

---

四、组件中读取环境变量

4.1 在 <script setup> 中使用

VTJ 使用 Composition API 模式，环境变量通过 __provider.env 全局实例访问：

// 读取单个变量
const baseUrl = __provider.env.BASE_URL;

// 带默认值的安全读取
const apiKey = __provider.env.API_KEY || 'default-key';

// 用于 API 请求前缀
const fullUrl = `${__provider.env.BASE_URL}/api/users`;

4.2 在模板中使用

<template>
  <div>
    <p>应用标题: {{ __provider.env.APP_TITLE }}</p>
    <p>API 地址: {{ __provider.env.BASE_URL }}</p>
  </div>
</template>

4.3 完整 SFC 示例

<template>
  <div class="page">
    <h1>{{ __provider.env.APP_TITLE || 'VTJ' }}</h1>
    <el-button @click="__state.loadData">加载数据</el-button>
  </div>
</template>

<script setup>
  import { reactive } from 'vue';

  const __state = reactive({
    data: null,
    loading: false,
    async loadData() {
      this.loading = true;
      const res = await __apis['getDashboard']();
      this.data = res.data?.data || null;
      this.loading = false;
    }
  });

  onMounted(() => {
    // 开发环境下打印日志
    if (__provider.env.DEBUG === 'true') {
      console.log('当前 BASE_URL:', __provider.env.BASE_URL);
    }
  });
</script>

---

五、典型使用场景

5.1 API 基础地址

{
  "action": "createEnv",
  "parameters": [
    {
      "name": "API_BASE_URL",
      "development": "http://localhost:3000/api",
      "production": "https://api.myapp.com"
    }
  ]
}

组件中使用环境变量拼接 API URL：

// 注意：API 的 url 字段可直接使用相对路径 /api/users，
// 实际请求地址由全局 axios 的 baseURL 决定。
// 环境变量更适用于非请求场景的地址引用。
const uploadUrl = `${__provider.env.API_BASE_URL}/upload`;

5.2 功能开关

{
  "action": "createEnv",
  "parameters": [
    {
      "name": "ENABLE_DEBUG_PANEL",
      "development": "true",
      "production": "false"
    }
  ]
}

组件中：

<debug-panel v-if="__provider.env.ENABLE_DEBUG_PANEL === 'true'" />

5.3 第三方 Key / 配置

{
  "action": "createEnv",
  "parameters": [
    {
      "name": "MAP_KEY",
      "development": "dev-abc123",
      "production": "prod-xyz789"
    }
  ]
}

---

六、注意事项

1. 值类型为字符串： EnvConfig 的 development 和 production 字段类型均为 string，布尔值需使用 'true' / 'false' 字符串
2. 同名不覆盖： createEnv 不检查同名变量是否已存在，直接追加。如需更新，建议先 removeEnv 再 createEnv
3. 运行时自动选取： initEnv() 根据 provider.nodeEnv（development 或 production）自动选择对应值，无需手动判断环境
4. 变量名约定： 推荐使用大写字母 + 下划线命名（UPPER_SNAKE_CASE），如 BASE_URL、APP_TITLE
5. 脚本层访问： 环境变量通过 __provider.env 实例属性访问，不是 $provider.env 或 this.$provider.env
6. 不在 __state 中存储： 环境变量是全局只读配置，不要将 __provider.env 的值复制到 __state 中，直接在需要的地方读取即可
7. 不需要手动 import： __provider 由框架在组件模板中通过 useProvider() 自动声明，组件内直接使用