# robot-admin-env-manager

**Repository Path**: ycyplus163/robot-admin-env-manager

## Basic Information

- **Project Name**: robot-admin-env-manager
- **Description**: robot-admin 框架的环境管理包，按照同样规范也可以帮助其他类似项目管理环境文件
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-23
- **Last Updated**: 2025-08-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🚀 @robot-admin/env-manager

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

[![npm version](https://badge.fury.io/js/%40robot-admin%2Fenv-manager.svg)](https://www.npmjs.com/package/@robot-admin/env-manager)
[![Downloads](https://img.shields.io/npm/dm/@robot-admin/env-manager.svg)](https://www.npmjs.com/package/@robot-admin/env-manager)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/Node.js-14%2B-green.svg)](https://nodejs.org/)

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

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

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

## ✨ 为什么选择 env-manager？

### 🎨 **精美的命令行界面**
```bash
────────────────────────────────────────────────────────
◆ Robot Admin — 环境配置管理工具 v2.1.3

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

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

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

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

### 💡 **现代化设计**
- ✅ **精致界面** - 使用现代化图标和颜色系统
- ✅ **零依赖** - 只使用 Node.js 内置模块，启动飞快
- ✅ **TypeScript 友好** - 完整的类型定义支持
- ✅ **真实版本** - 动态读取 package.json 版本号

## 📦 安装

### 全局安装（推荐）
```bash
npm install -g @robot-admin/env-manager
```

### 项目内安装
```bash
npm install --save-dev @robot-admin/env-manager
```

## 🚀 快速开始

### 1️⃣ 初始化项目
```bash
# 在你的项目根目录运行
env-manager --init
```

执行后你会看到：
```bash
────────────────────────────────────────────────────────
◆ 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（通用配置）**
```bash
# 所有环境共享的配置
APP_NAME=我的超赞项目
APP_VERSION=1.0.0
DATABASE_TIMEOUT=30000
UPLOAD_MAX_SIZE=10485760
```

**envs/.env.development（开发环境）**
```bash
# 开发环境特定配置
NODE_ENV=development
API_URL=http://localhost:3000
DATABASE_URL=mongodb://localhost:27017/myapp_dev
DEBUG=true
MOCK_DATA=true
```

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

### 3️⃣ 一键切换环境
```bash
# 切换到开发环境
env-manager dev

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

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

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

扫描环境文件的输出示例：
```bash
────────────────────────────────────────────────────────
◆ Robot Admin — 环境配置管理工具 v2.1.3

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

## 💡 使用场景

### 🔥 **场景一：日常开发**
```bash
# 早上开始开发
env-manager dev
npm run start

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

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

### 🚀 **场景二：CI/CD 集成**
```bash
# 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
```

### 👥 **场景三：团队协作**
```bash
# 新同事入职
git clone your-project
cd your-project
npm install
env-manager --init        # 创建环境文件模板
env-manager dev          # 一键配置开发环境
npm run dev              # 开始开发，环境已就绪！
```

### 🔧 **场景四：多项目管理**
```bash
# 项目A - 电商平台
cd project-a
env-manager prod         # 切换到生产环境
npm run deploy

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

## 📖 完整 API 文档

### 🖥️ **命令行接口**

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

#### 支持的环境类型
| 环境名称 | 别名 | 对应文件 | 使用场景 |
|---------|-----|----------|----------|
| `dev` | `development` | `.env.development` | 🔥 本地开发 |
| `test` | - | `.env.test` | 🧪 自动化测试 |
| `staging` | `stage` | `.env.staging` | 🚀 预发布验证 |
| `prod` | `production` | `.env.production` | 💎 生产环境 |

#### 高级选项
```bash
env-manager dev --force      # 强制切换（跳过确认）
env-manager --init --force   # 强制重新初始化（覆盖现有文件）
```

### 📝 **编程式 API**

#### ES6 模块
```javascript
import { switchEnv, scanEnvs, initProject } from '@robot-admin/env-manager'

// 切换环境
await switchEnv('production', {
  envsDir: 'config/envs',    // 自定义环境文件目录
  targetFile: '.env.local',   // 自定义输出文件
  silent: false              // 是否静默模式
})

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

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

#### CommonJS
```javascript
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 })
  }
})
```

#### 类模式（向后兼容）
```javascript
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. **合并策略**: 
   - 如果变量在环境特定文件中存在，使用环境特定的值
   - 如果变量只在通用文件中存在，使用通用的值
   - 自动添加注释说明变量来源

**示例合并结果：**
```bash
# ✨ 自动生成的环境配置文件
# 🚀 由 @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 # (被环境特定配置覆盖)
```

### 📋 **最佳实践**

#### ✅ **推荐做法**
```bash
# 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
```

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

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

## 🎨 界面设计特色

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

### 📋 **统一输出格式**
所有操作都使用统一的输出块格式：
```bash
────────────────────────────────────────────────────────
◆ Robot Admin — 环境配置管理工具 v2.1.3

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

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

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

## 🛠️ 项目集成

### 📦 **在 package.json 中集成**
```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 集成**
```dockerfile
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 集成**
```yaml
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 集成**
```javascript
// 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)
    }
  }
})
```

## 🔐 安全最佳实践

### 🛡️ **文件权限管理**
```bash
# .gitignore 配置
.env
.env.local
.env.*.local

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

### 🔒 **敏感信息处理**
```bash
# envs/.env.production
# 使用环境变量或密钥管理服务
DATABASE_URL=${DATABASE_URL}
API_SECRET=${API_SECRET}
JWT_SECRET=${JWT_SECRET}

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

## 🚨 常见问题

<details>
<summary><strong>Q: 为什么我的 .env 文件没有生效？</strong></summary>

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

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

你应该看到类似这样的输出：
```bash
────────────────────────────────────────────────────────
◆ Robot Admin — 环境配置管理工具 v2.1.3

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

<details>
<summary><strong>Q: 如何在团队中共享环境配置？</strong></summary>

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

```bash
# 团队成员的操作流程
git clone your-project
cd your-project
npm install
env-manager --init
env-manager dev
```
</details>

<details>
<summary><strong>Q: 可以自定义环境文件目录吗？</strong></summary>

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

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

<details>
<summary><strong>Q: 为什么要使用精致的界面设计？</strong></summary>

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

## 🤝 贡献指南

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

### 🐛 **报告 Bug**
在 [GitHub Issues](https://github.com/robot-admin/env-manager/issues) 中报告问题时，请包含：
- 操作系统和 Node.js 版本
- 完整的错误信息
- 重现步骤
- 期望的行为

### 💡 **功能建议**
我们希望听到你的想法！请在 Issues 中描述：
- 功能的使用场景
- 具体的实现建议
- 相关的技术细节

### 🔧 **代码贡献**
```bash
# 1. Fork 项目
git clone https://github.com/your-username/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](https://www.conventionalcommits.org/)：
- `feat:` 新功能
- `fix:` Bug 修复
- `docs:` 文档更新
- `style:` 代码格式调整
- `refactor:` 代码重构
- `test:` 测试相关
- `chore:` 构建工具、依赖更新等


## 📊 项目统计

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

## 🙏 致谢

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

特别感谢：
- [dotenv](https://github.com/motdotla/dotenv) - 启发了环境变量管理的最佳实践
- [chalk](https://github.com/chalk/chalk) - 命令行颜色输出的灵感来源
- [commander](https://github.com/tj/commander.js) - 命令行解析的设计参考
- [Vercel CLI](https://vercel.com/cli) - 现代化CLI界面设计的灵感来源

## 📄 许可证

MIT © [Robot Admin Team](https://robot-admin.com)

---

<div align="center">

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

[🐛 报告问题](https://github.com/robot-admin/env-manager/issues) • [💡 功能建议](https://github.com/robot-admin/env-manager/issues) • [💬 讨论交流](https://github.com/robot-admin/env-manager/discussions)

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

</div>