⚡

环境变量映射器Skill env-var-mapper

环境变量映射器是一个用于自动化生成环境变量到命令行参数映射配置的工具技能。它支持环境变量前缀命名、类型安全转换、配置回退链和.env文件加载，能够为TypeScript、Python、Go等多种编程语言生成配置管理代码。主要功能包括：环境变量映射配置、前缀支持、类型转换、回退机制、自动文档生成。适用于CLI工具开发、微服务配置管理、DevOps自动化等场景。关键词：环境变量配置、CLI参数映射、配置管理、DevOps工具、自动化代码生成、类型安全、前缀命名、回退链、.env文件支持。

DevOps 0 次安装 0 次浏览 更新于 2/23/2026

name: env-var-mapper description: 生成环境变量到命令行参数的映射，支持前缀、类型转换和配置回退链。 allowed-tools: Read, Write, Edit, Bash, Glob, Grep

环境变量映射器

为灵活配置生成环境变量到命令行参数的映射。

能力

  • 生成环境变量到参数的映射逻辑
  • 创建基于前缀的环境变量加载
  • 为环境变量设置类型转换
  • 实现回退链（环境变量 -> 配置文件 -> 默认值）
  • 配置 .env 文件支持
  • 生成环境变量文档

使用场景

在以下情况下调用此技能：

  • 将环境变量映射到命令行参数
  • 创建基于前缀的配置加载
  • 实现配置回退链
  • 在 CLI 应用程序中支持 .env 文件

输入参数

参数 类型 是否必需 描述
language string 是 目标语言（typescript, python, go）
prefix string 否 环境变量前缀（例如：MYAPP_）
mappings array 是 环境变量映射配置
dotenvSupport boolean 否 启用 .env 文件支持（默认：true）

映射结构

{
  "mappings": [
    {
      "envVar": "PORT",
      "argument": "port",
      "type": "number",
      "default": 3000,
      "description": "服务器端口"
    },
    {
      "envVar": "DATABASE_URL",
      "argument": "database-url",
      "type": "string",
      "required": true,
      "sensitive": true
    },
    {
      "envVar": "DEBUG",
      "argument": "debug",
      "type": "boolean",
      "default": false
    }
  ]
}

生成的代码模式

TypeScript 映射器

import { config } from 'dotenv';
import { z } from 'zod';

// 加载 .env 文件
config();

const ENV_PREFIX = 'MYAPP_';

// 环境变量模式
const envSchema = z.object({
  PORT: z.coerce.number().default(3000),
  DATABASE_URL: z.string().min(1),
  DEBUG: z.coerce.boolean().default(false),
  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
});

// 获取带前缀的环境变量
function getEnv(name: string): string | undefined {
  return process.env[`${ENV_PREFIX}${name}`] ?? process.env[name];
}

// 构建带前缀支持的环境对象
function buildEnvObject(): Record<string, string | undefined> {
  return {
    PORT: getEnv('PORT'),
    DATABASE_URL: getEnv('DATABASE_URL'),
    DEBUG: getEnv('DEBUG'),
    LOG_LEVEL: getEnv('LOG_LEVEL'),
  };
}

// 解析和验证环境变量
export function loadEnvironment() {
  const env = buildEnvObject();
  return envSchema.parse(env);
}

// 将环境变量映射到命令行参数
export function envToArgs(): string[] {
  const env = loadEnvironment();
  const args: string[] = [];

  if (env.PORT !== 3000) {
    args.push('--port', String(env.PORT));
  }
  if (env.DATABASE_URL) {
    args.push('--database-url', env.DATABASE_URL);
  }
  if (env.DEBUG) {
    args.push('--debug');
  }
  if (env.LOG_LEVEL !== 'info') {
    args.push('--log-level', env.LOG_LEVEL);
  }

  return args;
}

// 生成文档
export const ENV_DOCS = `
环境变量：

  ${ENV_PREFIX}PORT          服务器端口（默认：3000）
  ${ENV_PREFIX}DATABASE_URL  数据库连接 URL（必需）
  ${ENV_PREFIX}DEBUG         启用调试模式（默认：false）
  ${ENV_PREFIX}LOG_LEVEL     日志级别：debug|info|warn|error（默认：info）
`;

Python 映射器

import os
from dataclasses import dataclass
from typing import Optional
from dotenv import load_dotenv

# 加载 .env 文件
load_dotenv()

ENV_PREFIX = 'MYAPP_'

@dataclass
class Environment:
    port: int = 3000
    database_url: str = ''
    debug: bool = False
    log_level: str = 'info'

def get_env(name: str) -> Optional[str]:
    """获取带前缀回退的环境变量。"""
    return os.getenv(f'{ENV_PREFIX}{name}') or os.getenv(name)

def parse_bool(value: Optional[str]) -> bool:
    """从环境变量解析布尔值。"""
    if value is None:
        return False
    return value.lower() in ('true', '1', 'yes', 'on')

def load_environment() -> Environment:
    """加载和验证环境变量。"""
    env = Environment()

    if port := get_env('PORT'):
        env.port = int(port)

    if database_url := get_env('DATABASE_URL'):
        env.database_url = database_url
    else:
        raise ValueError('DATABASE_URL 是必需的')

    env.debug = parse_bool(get_env('DEBUG'))

    if log_level := get_env('LOG_LEVEL'):
        if log_level not in ('debug', 'info', 'warn', 'error'):
            raise ValueError(f'无效的 LOG_LEVEL: {log_level}')
        env.log_level = log_level

    return env

def env_to_args() -> list[str]:
    """将环境变量转换为命令行参数。"""
    env = load_environment()
    args = []

    if env.port != 3000:
        args.extend(['--port', str(env.port)])
    if env.database_url:
        args.extend(['--database-url', env.database_url])
    if env.debug:
        args.append('--debug')
    if env.log_level != 'info':
        args.extend(['--log-level', env.log_level])

    return args

ENV_DOCS = f'''
环境变量：

  {ENV_PREFIX}PORT          服务器端口（默认：3000）
  {ENV_PREFIX}DATABASE_URL  数据库连接 URL（必需）
  {ENV_PREFIX}DEBUG         启用调试模式（默认：false）
  {ENV_PREFIX}LOG_LEVEL     日志级别：debug|info|warn|error（默认：info）
'''

Go 映射器

package config

import (
    "fmt"
    "os"
    "strconv"
    "strings"

    "github.com/joho/godotenv"
)

const EnvPrefix = "MYAPP_"

type Environment struct {
    Port        int
    DatabaseURL string
    Debug       bool
    LogLevel    string
}

func init() {
    // 如果存在则加载 .env 文件
    godotenv.Load()
}

func getEnv(name string) string {
    if val := os.Getenv(EnvPrefix + name); val != "" {
        return val
    }
    return os.Getenv(name)
}

func parseBool(value string) bool {
    lower := strings.ToLower(value)
    return lower == "true" || lower == "1" || lower == "yes" || lower == "on"
}

func LoadEnvironment() (*Environment, error) {
    env := &Environment{
        Port:     3000,
        Debug:    false,
        LogLevel: "info",
    }

    if port := getEnv("PORT"); port != "" {
        p, err := strconv.Atoi(port)
        if err != nil {
            return nil, fmt.Errorf("无效的 PORT: %s", port)
        }
        env.Port = p
    }

    env.DatabaseURL = getEnv("DATABASE_URL")
    if env.DatabaseURL == "" {
        return nil, fmt.Errorf("DATABASE_URL 是必需的")
    }

    env.Debug = parseBool(getEnv("DEBUG"))

    if logLevel := getEnv("LOG_LEVEL"); logLevel != "" {
        valid := []string{"debug", "info", "warn", "error"}
        found := false
        for _, v := range valid {
            if v == logLevel {
                found = true
                break
            }
        }
        if !found {
            return nil, fmt.Errorf("无效的 LOG_LEVEL: %s", logLevel)
        }
        env.LogLevel = logLevel
    }

    return env, nil
}

工作流程

  1. 定义映射 - 指定环境变量和参数
  2. 配置前缀 - 设置应用程序前缀
  3. 生成加载器 - 创建环境变量加载代码
  4. 添加类型转换 - 处理类型强制转换
  5. 生成文档 - 创建环境变量文档
  6. 添加验证 - 必需字段和约束

应用的最佳实践

  • 前缀支持命名空间
  • 从带前缀回退到无前缀
  • 类型安全的环境变量解析
  • 布尔字符串解析
  • .env 文件支持
  • 自动生成的文档

目标流程

  • 参数解析器设置
  • 配置管理系统
  • CLI 应用程序引导