🚀 robot-admin-env-manager

专为现代前端项目设计的环境配置管理工具 | 告别环境变量混乱，拥抱优雅开发体验

English | 中文

😫 你是否遇到过这些问题？

• 开发时连错数据库？ 因为 .env 文件忘记切换环境
• 部署出错？ 测试环境的配置意外推到了生产环境
• 团队协作困难？ 每个人的环境配置文件都不一样
• 配置文件被误删？ 重要的环境变量找不回来了
• 多环境管理混乱？ dev、test、staging、prod 配置到处都是

如果你点头了，那么这个工具就是为你而生的！ 🎯

✨ 为什么选择 env-manager？

🎨 精美的命令行界面

────────────────────────────────────────────────────────
◆ Robot Admin — 环境配置管理工具 v2.1.3

   ◐ 开始处理   → production 环境
   ✓ 通用配置   → 读取成功
   ✓ 环境配置   → 读取成功
   ⚙ 合并配置   → 已完成
   ⚙ 写入文件   → 已完成

✓ 环境切换成功 → PRODUCTION • 12 个变量 • 已生效
────────────────────────────────────────────────────────

🛡️ 安全可靠

• ✅ 零误操作 - 智能验证，防止配置错误
• ✅ 精致界面 - 统一的输出块设计，信息清晰可读
• ✅ 权限检查 - 确保有足够权限进行文件操作
• ✅ 格式验证 - 自动检查环境变量格式

🚀 开发体验极佳

• ✅ 一键切换 - env-manager dev 秒速切换到开发环境
• ✅ 智能合并 - 自动合并通用配置和环境特定配置
• ✅ 零学习成本 - 简单直观，看一眼就会用
• ✅ 多平台支持 - Windows、macOS、Linux 通用

💡 现代化设计

• ✅ 精致界面 - 使用现代化图标和颜色系统
• ✅ 零依赖 - 只使用 Node.js 内置模块，启动飞快
• ✅ CommonJS & ESM 友好 - 支持 require / import 两种用法
• ✅ 真实版本 - 动态读取 package.json 版本号

📦 安装

全局安装（推荐）

npm install -g robot-admin-env-manager

项目内安装

npm install --save-dev robot-admin-env-manager

🚀 快速开始

1️⃣ 初始化项目

# 在你的项目根目录运行
env-manager --init

执行后你会看到：

────────────────────────────────────────────────────────
◆ Robot Admin — 环境配置管理工具 v2.1.3

   ⚙ 初始化项目   → 开始处理
   ✓ .env         → 创建成功
   ✓ .env.development → 创建成功
   ✓ .env.test    → 创建成功
   ✓ .env.staging → 创建成功
   ✓ .env.production → 创建成功

快速使用:
   env-manager dev       → 开发环境
   env-manager prod      → 生产环境
   env-manager --scan    → 扫描文件
────────────────────────────────────────────────────────

这会创建以下文件结构：

your-project/
├── envs/
│   ├── .env                    # 🔧 通用配置
│   ├── .env.development        # 🔥 开发环境
│   ├── .env.test              # 🧪 测试环境
│   ├── .env.staging           # 🚀 预发布环境
│   └── .env.production        # 💎 生产环境
└── .env                       # ⚡ 当前激活的环境配置

2️⃣ 配置你的环境文件

envs/.env（通用配置）

# 所有环境共享的配置
APP_NAME=我的超赞项目
APP_VERSION=1.0.0
DATABASE_TIMEOUT=30000
UPLOAD_MAX_SIZE=10485760

envs/.env.development（开发环境）

# 开发环境特定配置
NODE_ENV=development
API_URL=http://localhost:3000
DATABASE_URL=mongodb://localhost:27017/myapp_dev
DEBUG=true
MOCK_DATA=true

envs/.env.production（生产环境）

# 生产环境特定配置
NODE_ENV=production  
API_URL=https://api.myapp.com
DATABASE_URL=mongodb://prod-cluster:27017/myapp
DEBUG=false
ENABLE_ANALYTICS=true

3️⃣ 一键切换环境

# 切换到开发环境
env-manager dev

# 切换到生产环境  
env-manager prod

# 切换到测试环境
env-manager test

# 查看所有可用环境
env-manager --scan

扫描环境文件的输出示例：

────────────────────────────────────────────────────────
◆ Robot Admin — 环境配置管理工具 v2.1.3

发现环境文件:
   ◉ .env                      → 0.2KB
   ◉ .env.development          → 0.3KB
   ◉ .env.test                 → 0.2KB
   ◉ .env.staging              → 0.3KB
   ◉ .env.production           → 0.4KB
────────────────────────────────────────────────────────

💡 使用场景

🔥 场景一：日常开发

# 早上开始开发
env-manager dev
npm run start

# 需要测试时
env-manager test  
npm run test

# 准备部署
env-manager prod
npm run build

🚀 场景二：CI/CD 集成

# GitHub Actions
- name: Setup Environment
  run: |
    npm install -g robot-admin-env-manager
    env-manager production
    npm run build

# Docker 部署
FROM node:18-alpine
RUN npm install -g robot-admin-env-manager
COPY envs/ ./envs/
RUN env-manager production

👥 场景三：团队协作

# 新同事入职
git clone your-project
cd your-project
npm install
env-manager --init        # 创建环境文件模板
env-manager dev          # 一键配置开发环境
npm run dev              # 开始开发，环境已就绪！

🔧 场景四：多项目管理

# 项目A - 电商平台
cd project-a
env-manager prod         # 切换到生产环境
npm run deploy

# 项目B - 管理后台  
cd ../project-b
env-manager staging      # 切换到预发布环境
npm run test

📖 完整 API 文档

🖥️ 命令行接口

基础命令

env-manager <environment>    # 切换到指定环境
env-manager --init          # 初始化项目环境文件
env-manager --scan          # 扫描可用的环境文件
env-manager --help          # 显示帮助信息
env-manager --version       # 显示版本号

支持的环境类型

| 环境名称 | 别名 | 对应文件 | 使用场景 | |---------|-----|----------|----------| | dev | development, local | .env.development | 🔥 本地开发 | | test | - | .env.test | 🧪 自动化测试 | | staging | stage, uat | .env.staging | 🚀 预发布验证 | | prod | production | .env.production | 📎 生产环境 |

高级选项

env-manager prod --backup              # 切换前备份当前 .env 为 .env.backup
env-manager prod --dry-run             # 预览合并结果，不实际写入文件
env-manager dev --envsDir=config/envs  # 自定义环境文件目录
env-manager dev --target=.env.local    # 自定义输出文件路径
env-manager --init --force             # 强制重新初始化（覆盖已有文件）
env-manager --scan --envsDir=config    # 扫描自定义目录

📝 编程式 API

ES6 模块

import { switchEnv, scanEnvs, initProject } from 'robot-admin-env-manager'

// 切换环境
await switchEnv('production', {
  envsDir: 'config/envs',    // 自定义环境文件目录
  targetFile: '.env.local',   // 自定义输出文件
  backup: true,              // 切换前备份当前 .env
  dryRun: false,             // 是否仅预览
  silent: false              // 是否静默模式
})

// 扫描环境文件
const envFiles = await scanEnvs({ envsDir: 'envs' })
console.log('找到环境文件:', envFiles)

// 初始化项目
await initProject({ 
  envsDir: 'envs',
  force: false 
})

CommonJS

const { switchEnv, scanEnvs, initProject } = require('robot-admin-env-manager')

// 在 Express 应用中使用
app.post('/api/switch-env', async (req, res) => {
  try {
    const { environment } = req.body
    const result = await switchEnv(environment)
    res.json({ success: true, result })
  } catch (error) {
    res.status(500).json({ error: error.message })
  }
})

类模式（向后兼容）

const EnvManager = require('robot-admin-env-manager')

const manager = new EnvManager({
  envsDir: 'custom-envs',
  targetFile: '.env.local',
  silent: true
})

await manager.switchEnvironment('production')
await manager.scanEnvironmentFiles()
await manager.initializeProject()

🔧 配置文件详解

🗂️ 目录结构

your-project/
├── envs/                      # 环境配置目录
│   ├── .env                   # 通用配置（所有环境共享）
│   ├── .env.development       # 开发环境配置
│   ├── .env.test             # 测试环境配置
│   ├── .env.staging          # 预发布环境配置
│   └── .env.production       # 生产环境配置
├── .env                      # 当前激活的环境配置（自动生成）
└── .gitignore               # 确保 .env 被忽略

🔀 配置合并规则

env-manager 会智能合并配置文件：

1. 优先级: 环境特定配置 > 通用配置
2. 合并策略:
   • 如果变量在环境特定文件中存在，使用环境特定的值
   • 如果变量只在通用文件中存在，使用通用的值
   • 自动添加注释说明变量来源

示例合并结果：

# ✨ 自动生成的环境配置文件
# 🚀 由 robot-admin-env-manager 生成 (development 环境)
# ⚠️  请勿手动编辑此文件
# 📝 最后更新: 2024-01-15 10:30:25

# ═══════════════ 环境特定配置 ═══════════════
NODE_ENV=development
API_URL=http://localhost:3000
DEBUG=true

# ═══════════════ 通用配置 ═══════════════
APP_NAME=我的超赞项目
APP_VERSION=1.0.0
# DATABASE_URL=mongodb://prod:27017/app # (被环境特定配置覆盖)

📋 最佳实践

✅ 推荐做法

# envs/.env - 通用配置
APP_NAME=MyApp
APP_VERSION=1.0.0
DEFAULT_LOCALE=zh-CN
TIMEZONE=Asia/Shanghai

# envs/.env.development - 开发环境
NODE_ENV=development
API_URL=http://localhost:3000
DEBUG=true
LOG_LEVEL=debug

# envs/.env.production - 生产环境
NODE_ENV=production
API_URL=https://api.myapp.com
DEBUG=false
LOG_LEVEL=error

❌ 避免的做法

# 不要在通用配置中放环境特定的值
API_URL=http://localhost:3000  # ❌ 这是开发环境特定的

# 不要在环境文件中重复通用配置
APP_NAME=MyApp  # ❌ 这应该在通用配置中

🎨 界面设计特色

🌈 现代化颜色系统

• 主色调: 现代蓝紫色系，专业且不失活力
• 状态颜色: 成功（绿✓）、警告（黄⚠）、错误（红✕）、信息（蓝◉）
• 精致图标: 使用 Unicode 符号，无需额外字体

📋 统一输出格式

所有操作都使用统一的输出块格式：

────────────────────────────────────────────────────────
◆ Robot Admin — 环境配置管理工具 v2.1.3

   [图标] 操作描述   → 详细信息

✓ 最终结果 → 关键信息 • 统计数据 • 状态
────────────────────────────────────────────────────────

🎯 清晰的信息层级

• 品牌标识: ◆ + 工具名称 + 版本号
• 处理过程: 带箭头的清晰步骤
• 最终结果: 突出的成功卡片设计
• 文字对齐: 所有文本都精确对齐

🛠️ 项目集成

📦 在 package.json 中集成

{
  "scripts": {
    "env:dev": "env-manager dev",
    "env:test": "env-manager test",
    "env:staging": "env-manager staging", 
    "env:prod": "env-manager prod",
    
    "dev": "env-manager dev && npm run start:dev",
    "test": "env-manager test && npm run test:unit",
    "build:staging": "env-manager staging && npm run build",
    "build:prod": "env-manager prod && npm run build",
    
    "deploy:staging": "npm run build:staging && npm run deploy",
    "deploy:prod": "npm run build:prod && npm run deploy"
  }
}

🐳 Docker 集成

FROM node:18-alpine

# 安装 env-manager
RUN npm install -g robot-admin-env-manager

# 复制环境配置
COPY envs/ ./envs/

# 根据构建参数设置环境
ARG NODE_ENV=production
RUN env-manager ${NODE_ENV}

# 构建应用
COPY . .
RUN npm ci && npm run build

CMD ["npm", "start"]

⚙️ GitHub Actions 集成

name: Build and Deploy

on:
  push:
    branches: [main, develop]

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
          
      - name: Install dependencies
        run: npm ci
        
      - name: Setup environment
        run: |
          npm install -g robot-admin-env-manager
          env-manager ${{ github.ref == 'refs/heads/main' && 'production' || 'staging' }}
          
      - name: Build
        run: npm run build
        
      - name: Deploy
        run: npm run deploy

🔧 Webpack/Vite 集成

// webpack.config.js
const path = require('path')

module.exports = {
  // Webpack 会自动读取 .env 文件
  plugins: [
    new webpack.DefinePlugin({
      'process.env': JSON.stringify(process.env)
    })
  ]
}

// vite.config.js
import { defineConfig, loadEnv } from 'vite'

export default defineConfig(({ mode }) => {
  // env-manager 生成的 .env 文件会被自动加载
  const env = loadEnv(mode, process.cwd(), '')
  
  return {
    define: {
      __APP_ENV__: JSON.stringify(env.NODE_ENV)
    }
  }
})

🔐 安全最佳实践

🛡️ 文件权限管理

# .gitignore 配置
.env
.env.local
.env.*.local

# 但要保留环境文件模板
!envs/.env.example
!envs/.env.development.example

🔒 敏感信息处理

# envs/.env.production
# 使用环境变量或密钥管理服务
DATABASE_URL=${DATABASE_URL}
API_SECRET=${API_SECRET}
JWT_SECRET=${JWT_SECRET}

# 或使用占位符，部署时替换
DATABASE_URL=__DATABASE_URL__
API_SECRET=__API_SECRET__

🚨 常见问题

A: 请检查以下几点：

1. 确保已运行 env-manager <environment> 切换环境
2. 检查应用是否正确加载了 .env 文件
3. 确认环境变量名称格式正确（字母、数字、下划线）
4. 重启你的应用服务

# 验证环境文件
env-manager --scan
cat .env

你应该看到类似这样的输出：

────────────────────────────────────────────────────────
◆ Robot Admin — 环境配置管理工具 v2.1.3

发现环境文件:
   ◉ .env                      → 0.2KB
   ◉ .env.development          → 0.3KB
   ◉ .env.test                 → 0.2KB
   ◉ .env.staging              → 0.3KB
   ◉ .env.production           → 0.4KB
────────────────────────────────────────────────────────

A: 推荐的做法：

1. 将 envs/ 目录提交到 Git
2. 在 .gitignore 中排除 .env 文件
3. 团队成员克隆代码后运行 env-manager --init
4. 根据需要修改 envs/ 中的配置文件

# 团队成员的操作流程
git clone your-project
cd your-project
npm install
env-manager --init
env-manager dev

A: 当然可以！支持多种自定义方式：

# 编程式方式
const { switchEnv } = require('robot-admin-env-manager')
await switchEnv('dev', { envsDir: 'config/environments' })

A: 精致界面设计带来的好处：

1. 视觉完整性: 统一的输出块，每个操作都有明确边界
2. 信息清晰: 使用图标和颜色区分不同状态
3. 现代化体验: 符合现代 CLI 工具的设计理念
4. 易于阅读: 精确对齐的文本，提高可读性
5. 专业感: 给开发团队带来更好的工具使用体验

🤝 贡献指南

我们欢迎所有形式的贡献！

🐛 报告 Bug

在 GitHub Issues 中报告问题时，请包含：

• 操作系统和 Node.js 版本
• 完整的错误信息
• 重现步骤
• 期望的行为

💡 功能建议

我们希望听到你的想法！请在 Issues 中描述：

• 功能的使用场景
• 具体的实现建议
• 相关的技术细节

🔧 代码贡献

# 1. Fork 项目
git clone https://github.com/your-username/robot-admin-env-manager.git

# 2. 创建功能分支
git checkout -b feature/amazing-feature

# 3. 提交改动
git commit -m "feat: add amazing feature"

# 4. 推送分支
git push origin feature/amazing-feature

# 5. 创建 Pull Request

📝 提交规范

我们使用 Conventional Commits：

• feat: 新功能
• fix: Bug 修复
• docs: 文档更新
• style: 代码格式调整
• refactor: 代码重构
• test: 测试相关
• chore: 构建工具、依赖更新等

📊 项目统计

• 🚀 启动时间: < 100ms
• 📦 包大小: < 50KB
• 🔧 零外部依赖
• 🧪 测试覆盖率: 95%+
• 🌍 支持平台: Windows, macOS, Linux
• 🏗️ 支持运行时: Node.js 14+, Bun, Deno
• 🎨 现代化CLI界面: 精致的输出块设计

🙏 致谢

感谢所有为这个项目做出贡献的开发者们！

特别感谢：

• dotenv - 启发了环境变量管理的最佳实践
• chalk - 命令行颜色输出的灵感来源
• commander - 命令行解析的设计参考
• Vercel CLI - 现代化CLI界面设计的灵感来源

📄 许可证

MIT © Robot Admin Team

如果这个工具对你有帮助，请给我一个 ⭐️

🐛 报告问题 • 💡 功能建议 • 💬 讨论交流

让环境管理变得简单优雅 🚀