dev-environment-bootstrapper

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Dev Environment Bootstrapper

开发环境引导工具

Create consistent, reproducible development environments across all machines.

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

Core Workflow

核心工作流

Detect stack: Identify languages and tools used in project
Choose version manager: Select appropriate tool (Volta, asdf, mise, nvm, pyenv)
Generate configs: Create .tool-versions, .nvmrc, package.json volta fields, etc.
Setup environment vars: Create .env.example with all required variables
Write setup script: Generate bootstrap script for automated setup
Create onboarding doc: Write SETUP.md with step-by-step instructions

检测技术栈：识别项目中使用的语言和工具
选择版本管理器：挑选合适的工具（Volta、asdf、mise、nvm、pyenv）
生成配置文件：创建.tool-versions、.nvmrc、package.json中的volta字段等
配置环境变量：创建包含所有必填变量的.env.example文件
编写安装脚本：生成用于自动化搭建的引导脚本
创建入职文档：撰写包含分步指引的SETUP.md

Version Management Strategies

版本管理策略

Volta (Recommended for Node.js)

Volta（推荐用于Node.js）

json

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

json

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

asdf (Multi-language)

asdf（多语言支持）

undefined

undefined

.tool-versions

nodejs 20.11.0 python 3.11.7 ruby 3.2.2

undefined

nodejs 20.11.0 python 3.11.7 ruby 3.2.2

undefined

mise (Modern alternative to asdf)

mise（asdf的现代替代工具）

toml

undefined

toml

undefined

.mise.toml

[tools] node = "20.11.0" python = "3.11"

undefined

[tools] node = "20.11.0" python = "3.11"

undefined

nvm (Node.js only)

nvm（仅支持Node.js）

undefined

undefined

.nvmrc

20.11.0

undefined

20.11.0

undefined

Environment Variables Template

环境变量模板

bash

undefined

bash

undefined

.env.example

Application

应用配置

NODE_ENV=development PORT=3000

Database

数据库配置

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

External APIs

外部API配置

OPENAI_API_KEY=sk-... STRIPE_SECRET_KEY=sk_test_...

Feature Flags

功能开关

ENABLE_FEATURE_X=false

undefined

ENABLE_FEATURE_X=false

undefined

Setup Script Structure

安装脚本结构

For Node.js Projects

适用于Node.js项目

bash

#!/bin/bash
set -e

echo "🚀 Setting up development environment..."

bash

#!/bin/bash
set -e

echo "🚀 正在搭建开发环境..."

Check prerequisites

检查前置依赖

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

command -v pnpm >/dev/null 2>&1 || { echo "正在安装pnpm..."; npm install -g pnpm; }

Install dependencies

安装依赖

echo "📦 Installing dependencies..." pnpm install

echo "📦 正在安装依赖包..." pnpm install

Setup environment

配置环境

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

echo "⚙️ 正在配置环境变量..." cp .env.example .env echo "请编辑.env文件填入你的配置值"

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"

undefined

if [ -f "prisma/schema.prisma" ]; then echo "🗄️ 正在配置数据库..." pnpm prisma generate pnpm prisma migrate dev fi

echo "✅ 搭建完成！执行 'pnpm dev' 启动服务"

undefined

For Python Projects

适用于Python项目

bash

#!/bin/bash
set -e

echo "🚀 Setting up development environment..."

bash

#!/bin/bash
set -e

echo "🚀 正在搭建开发环境..."

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'"

undefined

python manage.py migrate

echo "✅ 搭建完成！执行 'source venv/bin/activate && python manage.py runserver' 启动服务"

undefined

Onboarding Documentation Template

入职文档模板

markdown

undefined

markdown

undefined

Development Setup

开发环境搭建指南

Prerequisites

前置依赖

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

Node.js 20.11+（通过Volta管理）
pnpm 8.15+
PostgreSQL 15+
Redis 7+（可选）

Quick Start

快速开始

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


2. **Install tools** (if using Volta)

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

3. **Run setup script**

   ```bash
   ./scripts/setup.sh
   ```

4. **Configure environment**

   - Copy `.env.example` to `.env`
   - Fill in required values
   - See ENVIRONMENT_VARIABLES.md for details

5. **Start development server**
   ```bash
   pnpm dev
   ```

克隆代码仓库
bash
```
git clone <repo-url>
cd <repo-name>
```


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

   ```bash
   curl https://get.volta.sh | bash
   # Volta会自动使用package.json中指定的版本
   ```

3. **执行安装脚本**

   ```bash
   ./scripts/setup.sh
   ```

4. **配置环境变量**

   - 复制 `.env.example` 为 `.env`
   - 填入所有必填配置值
   - 详情请参考ENVIRONMENT_VARIABLES.md

5. **启动开发服务器**
   ```bash
   pnpm dev
   ```

Troubleshooting

问题排查

Port already in use

Kill process:
```
lsof -ti:3000 | xargs kill
```

Database connection failed

Check PostgreSQL is running:
```
pg_isready
```
Verify DATABASE_URL in .env

Node version mismatch

Install Volta: See step 2
Or use nvm:
```
nvm use
```

端口已被占用

杀死进程：
```
lsof -ti:3000 | xargs kill
```

数据库连接失败

检查PostgreSQL是否运行：
```
pg_isready
```
验证.env中的DATABASE_URL配置

Node版本不匹配

安装Volta：参考步骤2
或使用nvm：
```
nvm use
```

Common Commands

常用命令

bash

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

undefined

bash

pnpm dev          # 启动开发服务器
pnpm build        # 生产环境构建
pnpm test         # 运行测试
pnpm lint         # 代码质量检查
pnpm format       # 代码格式化

Cross-Platform Considerations

跨平台注意事项

Shell Scripts

Shell脚本

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

同时提供.sh（Unix系统）和.ps1（Windows系统）版本
或使用Node.js脚本实现真正的跨平台支持

Path Separators

路径分隔符

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

在脚本中使用Node.js的
```
path.join()
```
方法
避免硬编码
```
/
```
或
```
\
```

Line Endings

换行符

Configure .gitattributes:


- text=auto
  \*.sh text eol=lf

配置.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

工具	支持语言	自动切换版本	配置文件
Volta	Node、Yarn、pnpm	是	package.json
asdf	多语言	是	.tool-versions
mise	多语言	是	.mise.toml
nvm	仅Node.js	手动	.nvmrc
pyenv	仅Python	是	.python-version

Best Practices

最佳实践

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

在配置文件中固定精确版本，避免意外问题
在入职指南中记录所有依赖要求
在全新机器上测试安装脚本
保持.env.example包含所有变量
为常见问题提供排查方案
使用版本管理器替代手动安装
确保安装脚本具有幂等性（可安全多次执行）

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

undefined

每个开发环境引导工具都应包含以下内容：

版本管理器配置文件（.tool-versions、package.json的volta字段等）
包管理器选型说明
包含所有变量的.env.example
安装脚本（setup.sh或setup.js）
SETUP.md或DEVELOPMENT.md入职指南
问题排查章节
常用命令参考
前置依赖清单