支持 monorepo 项目结构

[cunoe]

问题描述

当前 envx.config.yaml 的 files 字段设计不能很好地支持 monorepo，需要支持多个 .env 文件分布在不同 package 的场景。

实际使用案例： LEAPERone 本身就是 monorepo，环境变量需要分发到 apps/web/.env、apps/api/.env、packages/db/.env 等不同位置。

期望行为

• files 支持配置多个目标路径
• 每个环境变量可以指定它属于哪些 target file
• envx load 时按照 target 分发到对应的 .env 文件
• 支持从 monorepo 根目录统一管理所有子包的环境变量

参考配置格式示例

version: 1
files:
  - apps/web/.env
  - apps/api/.env
  - packages/db/.env
env:
  DATABASE_URL:
    target:
      - apps/web/.env
      - packages/db/.env
  API_KEY:
    target: apps/api/.env

[leaperone-bot]

🤖 Leo 自动分析

Now I have a comprehensive understanding of the codebase. Let me provide the technical analysis.

---

技术分析：Issue #7 - 支持 monorepo 项目结构

一、问题概述

这是一个功能增强请求。当前 envx 在 envx load 写入 .env 文件时，会将所有环境变量写入到 files 字段指定的每一个文件中，不支持按变量粒度分发到不同的目标文件。在 monorepo 场景下（如 LEAPERone 项目本身），DATABASE_URL 应只写入 apps/web/.env 和 packages/db/.env，而 API_KEY 只写入 apps/api/.env，但目前做不到这一点。

二、当前架构分析

核心数据流：

envx.config.yaml → ConfigParser → ConfigManager → com.ts(writeEnvs) → env/index.ts(writeEnvFile)

关键发现：

1. 类型定义 (src/types/config.ts)：EnvConfig 已有 files?: string | string[] 字段，但 target 仅为 string 类型（用于引用远程源，非文件路径）
2. writeEnvs (src/utils/com.ts:65-73)：这是核心问题所在——它只读取全局 files，把全部 envMap 写入每个文件，完全忽略每个变量各自的 files 配置
3. getEnvs (src/utils/com.ts:7-55)：从 .env 文件读取时也是全局合并，不区分来源文件
4. ConfigValidator (config-validator.ts:60)：验证逻辑中 files 字段仍有 typeof config.files !== 'string' 的断言，不兼容数组类型（这是一个已存在的 bug）
5. Issue 中提到的 target 字段：Issue 建议用 target 来指定目标文件路径，但代码中 target 已被用作远程引用源标识（如 @username/project），语义冲突

三、需要修改的文件/模块

文件	修改内容	复杂度
src/types/config.ts	EnvConfig.files 语义从"clone源"改为"目标文件列表"，或新增 target_files 字段	低
src/utils/com.ts	核心改动：重写 writeEnvs，按变量的 files 配置分组写入不同文件；变量无 files 则 fallback 到全局 files	中
src/utils/com.ts	修改 getEnvs，按文件来源标记变量归属	中
src/utils/config/config-parser.ts	normalizeEnvValue 需要正确处理 files 为数组的情况	低
src/utils/config/config-validator.ts	修复 validateBasic 中 files 字段的验证逻辑（当前不兼容数组）；添加变量级 files 必须是全局 files 子集的校验	低
src/commands/load.ts	修改写入逻辑，按变量的 files 分组调用 writeEnvFile	中
src/commands/set.ts	writeEnvs 调用处需感知单变量的目标文件	低
src/commands/del.ts	删除时需从指定的目标文件中移除变量	低
src/commands/init.ts	支持多文件初始化场景	低

四、建议实现方案

推荐使用现有的 files 字段（而非 Issue 中提出的 target），因为：

• EnvConfig.files 已在类型定义中存在且类型为 string | string[]
• target 已被用于远程引用，语义不同
• 代码中已有 getEnvTargetFiles() 辅助函数但目前未被使用

配置格式应为：

version: 1
files:
  - apps/web/.env
  - apps/api/.env
  - packages/db/.env
env:
  DATABASE_URL:
    files:
      - apps/web/.env
      - packages/db/.env
  API_KEY:
    files: apps/api/.env
  SHARED_SECRET:   # 无 files → 写入所有全局 files

核心算法（writeEnvs 重写）：

export async function writeEnvs(configPath: string, envMap: EnvMap) {
  const configManager = new ConfigManager(configPath);
  const globalFiles = configManager.getEnvFilesConfig();
  const configDir = dirname(configPath);
  const allConfigs = configManager.getAllEnvConfigs();

  // 按目标文件分组
  const fileEnvMap: Record<string, EnvMap> = {};
  for (const file of globalFiles) {
    fileEnvMap[file] = {};
  }

  for (const [key, value] of Object.entries(envMap)) {
    const envConf = allConfigs.find(c => c.key === key);
    const targetFiles = envConf?.config.files
      ? (Array.isArray(envConf.config.files) ? envConf.config.files : [envConf.config.files])
      : globalFiles;  // fallback 到全局

    for (const file of targetFiles) {
      if (!fileEnvMap[file]) fileEnvMap[file] = {};
      fileEnvMap[file][key] = value;
    }
  }

  // 按文件写入
  for (const [file, envs] of Object.entries(fileEnvMap)) {
    const filePath = isAbsolute(file) ? file : join(configDir, file);
    await writeEnvFile(filePath, envs);
  }
}

五、复杂度评估

中等偏低（Medium-Low）

• 类型系统已预留了 files: string | string[]，无需大改类型
• 核心改动集中在 writeEnvs 函数（约 20 行核心逻辑）
• 其他命令的改动主要是适配性修改
• 无数据库 schema 变更
• 无破坏性变更（现有配置格式完全兼容）

六、风险与待确认问题

1. target vs files 命名：Issue 提案用 target，但代码中 target 已有远程引用语义。建议继续使用 files（已有类型定义），需与 Issue 作者确认
2. 变量级 files 必须是全局 files 的子集吗？ 建议是——否则会写入未在全局声明的文件，可能令人困惑。需要加验证
3. getEnvs 反向读取：当前从多个 .env 文件读取时是全量合并，如果两个文件有同名变量但值不同，会以最后读取的为准。monorepo 场景下这可能产生意外行为，需要考虑是否按 files 配置精确读取
4. ConfigValidator.validateBasic 中有 typeof config.files !== 'string' 的硬性检查，已经与现有类型定义 string | string[] 矛盾——这是一个存量 bug，应一并修复
5. 无测试覆盖：项目 package.json 的 test script 是空的（echo "Error: no test specified"），建议至少为核心的 writeEnvs 分发逻辑添加单元测试
6. 目录自动创建：写入 apps/web/.env 时，如果 apps/web/ 目录不存在，需要自动创建（当前 writeEnvFile 不处理此情况）