dev-environment-bootstrapper

开发环境引导工具

在所有机器上创建一致、可复现的开发环境。

核心工作流

1. 检测技术栈：识别项目使用的语言和工具
2. 选择版本管理工具：选择合适的工具（Volta、asdf、mise、nvm、pyenv）
3. 生成配置：创建 .tool-versions、.nvmrc、package.json 中的 volta 字段等
4. 设置环境变量：创建包含所有必需变量的 .env.example
5. 编写设置脚本：生成用于自动设置的引导脚本
6. 创建入门文档：编写 SETUP.md，提供分步说明

版本管理策略

Volta（推荐用于 Node.js）

// package.json
{
  "volta": {
    "node": "20.11.0",
    "pnpm": "8.15.0"
  }
}

asdf（多语言）

# .tool-versions
nodejs 20.11.0
python 3.11.7
ruby 3.2.2

mise（asdf 的现代替代方案）

# .mise.toml
[tools]
node = "20.11.0"
python = "3.11"

nvm（仅适用于 Node.js）

# .nvmrc
20.11.0

环境变量模板

# .env.example

# Application
NODE_ENV=development
PORT=3000

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/dbname

# External APIs
OPENAI_API_KEY=sk-...
STRIPE_SECRET_KEY=sk_test_...

# Feature Flags
ENABLE_FEATURE_X=false

设置脚本结构

Node.js 项目

#!/bin/bash
set -e

echo "🚀 Setting up development environment..."

# Check prerequisites
command -v pnpm >/dev/null 2>&1 || { echo "Installing pnpm..."; npm install -g pnpm; }

# Install dependencies
echo "📦 Installing dependencies..."
pnpm install

# Setup environment
echo "⚙️ Setting up environment variables..."
cp .env.example .env
echo "Edit .env file with your values"

# Setup database (if needed)
if [ -f "prisma/schema.prisma" ]; then
  echo "🗄️ Setting up database..."
  pnpm prisma generate
  pnpm prisma migrate dev
fi

echo "✅ Setup complete! Run 'pnpm dev' to start"

Python 项目

#!/bin/bash
set -e

echo "🚀 Setting up development environment..."

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Setup environment
cp .env.example .env

# Run migrations
python manage.py migrate

echo "✅ Setup complete! Run 'source venv/bin/activate && python manage.py runserver'"

入门文档模板

# Development Setup

## Prerequisites

- Node.js 20.11+ (managed via Volta)
- pnpm 8.15+
- PostgreSQL 15+
- Redis 7+ (optional)

## Quick Start

1. **Clone repository**
   ```bash
   git clone <repo-url>
   cd <repo-name>
   ```

2. 安装工具（如果使用 Volta）

   curl https://get.volta.sh | bash
   # Volta will automatically use versions from package.json
   

3. 运行设置脚本

   ./scripts/setup.sh
   

4. 配置环境

   • 将 .env.example 复制为 .env
   • 填写必需的值
   • 详情请参阅 ENVIRONMENT_VARIABLES.md

5. 启动开发服务器

   pnpm dev
   

故障排除

端口已被占用

• 结束进程：lsof -ti:3000 | xargs kill

数据库连接失败

• 检查 PostgreSQL 是否正在运行：pg_isready
• 验证 .env 中的 DATABASE_URL

Node 版本不匹配

• 安装 Volta：参阅第 2 步
• 或使用 nvm：nvm use

常用命令

pnpm dev          # Start dev server
pnpm build        # Build for production
pnpm test         # Run tests
pnpm lint         # Check code quality
pnpm format       # Format code

## Cross-Platform Considerations

### Shell Scripts
- Provide both .sh (Unix) and .ps1 (Windows) versions
- Or use Node.js scripts for true cross-platform

### Path Separators
- Use Node's `path.join()` in scripts
- Avoid hardcoded `/` or `\`

### Line Endings
- Configure .gitattributes:

• text=auto *.sh text eol=lf

## Version Manager Comparison

| Tool | Languages | Auto-switching | Config File |
|------|-----------|----------------|-------------|
| Volta | Node, Yarn, pnpm | Yes | package.json |
| asdf | Multi | Yes | .tool-versions |
| mise | Multi | Yes | .mise.toml |
| nvm | Node only | Manual | .nvmrc |
| pyenv | Python only | Yes | .python-version |

## Best Practices

1. **Pin exact versions** in configs to avoid surprises
2. **Document all requirements** in onboarding guide
3. **Test setup script** on clean machine
4. **Keep .env.example updated** with all variables
5. **Provide troubleshooting** for common issues
6. **Use tool version managers** over manual installs
7. **Make setup idempotent** (safe to run multiple times)

## Output Checklist

Every dev environment bootstrap should include:

- [ ] Version manager config (.tool-versions, package.json volta, etc.)
- [ ] Package manager choice documented
- [ ] .env.example with all variables
- [ ] Setup script (setup.sh or setup.js)
- [ ] SETUP.md or DEVELOPMENT.md onboarding guide
- [ ] Troubleshooting section
- [ ] Common commands reference
- [ ] Prerequisites listed