environment-setup-guide

环境设置指南

概述

帮助开发者从零开始设置完整的开发环境。本技能提供分步指南，介绍如何安装工具、配置依赖项、设置环境变量，以及验证环境是否正常运行。

何时使用此技能

• 开始新项目并需要设置开发环境时
• 为项目引入新团队成员时
• 切换到新设备或操作系统时
• 排查与环境相关的问题时
• 编写项目设置说明时
• 编写开发环境文档时

以下版本号仅为历史示例，并非当前受支持版本的建议。安装前请查看项目锁定文件、运行时约束和官方支持矩阵；不要假设较新的主版本兼容。安装依赖可能会执行生命周期脚本。请妥善保护机密环境文件，并将其加入 .gitignore。将用户加入 Docker 组会授予其相当于主机 root 的控制权限；适当情况下请使用无 root 模式的 Docker。此 Compose 配置仅用于本地开发：请使用独一无二的凭据，将发布的端口绑定到回环地址，并添加就绪检查，不要假设 depends_on 表示数据库已就绪。

工作原理

步骤 1：确定需求

我会帮助你确定需要安装的内容：

• 编程语言及其版本（Node.js、Python、Go 等）
• 包管理器（npm、pip、cargo 等）
• 数据库系统（PostgreSQL、MongoDB、Redis 等）
• 开发工具（Git、Docker、IDE 扩展等）
• 环境变量和配置文件

步骤 2：检查当前设置

在安装任何内容之前，我会帮助你检查已安装的内容：

# Check versions of installed tools
node --version
python --version
git --version
docker --version

步骤 3：提供安装说明

我会提供针对不同平台的安装命令：

• macOS： 使用 Homebrew
• Linux： 使用 apt、yum 或其他包管理器
• Windows： 使用 Chocolatey、Scoop 或直接运行安装程序

步骤 4：配置环境

帮助设置：

• 环境变量（.env 文件）
• 配置文件（.gitconfig、.npmrc 等）
• IDE 设置（VS Code、IntelliJ 等）
• Shell 配置（.bashrc、.zshrc 等）

步骤 5：验证安装

提供验证步骤，确保一切正常：

• 运行版本检查
• 测试基本命令
• 验证数据库连接
• 检查环境变量是否已加载

示例

示例 1：Node.js 项目设置

## Setting Up Node.js Development Environment

### Prerequisites
- macOS, Linux, or Windows
- Terminal/Command Prompt access
- Internet connection

### Step 1: Install Node.js

**macOS (using Homebrew):**
\`\`\`bash
# Install Homebrew if not installed
tmpdir="$(mktemp -d)"
trap 'rm -rf "$tmpdir"' EXIT
curl -fsSLo "$tmpdir/homebrew-install.sh" https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh
cat "$tmpdir/homebrew-install.sh"  # review the full installer before executing
/bin/bash "$tmpdir/homebrew-install.sh"

# Install Node.js
brew install node
\`\`\`

**Linux (Ubuntu/Debian):**
\`\`\`bash
# Update package list
sudo apt update

# Install Node.js and npm
tmpdir="$(mktemp -d)"
trap 'rm -rf "$tmpdir"' EXIT
curl -fsSLo "$tmpdir/nodesource-setup.sh" https://deb.nodesource.com/setup_20.x
cat "$tmpdir/nodesource-setup.sh"  # review the full installer before sudo
sudo -E bash "$tmpdir/nodesource-setup.sh"
sudo apt install -y nodejs
\`\`\`

**Windows (using winget):**
\`\`\`powershell
# Install Node.js
winget install OpenJS.NodeJS.LTS
\`\`\`

### Step 2: Verify Installation

\`\`\`bash
node --version  # Should show v20.x.x or higher
npm --version   # Should show 10.x.x or higher
\`\`\`

### Step 3: Install Project Dependencies

\`\`\`bash
# Clone the repository
git clone https://github.com/your-repo/project.git
cd project

# Install dependencies
npm install
\`\`\`

### Step 4: Set Up Environment Variables

Create a \`.env\` file:
\`\`\`bash
# Copy example environment file
cp .env.example .env

# Edit with your values
nano .env
\`\`\`

Example \`.env\` content:
\`\`\`
NODE_ENV=development
PORT=3000
DATABASE_URL=postgresql://localhost:5432/mydb
API_KEY=your-api-key-here
\`\`\`

### Step 5: Run the Project

\`\`\`bash
# Start development server
npm run dev

# Should see: Server running on http://localhost:3000
\`\`\`

### Troubleshooting

**Problem:** "node: command not found"
**Solution:** Restart your terminal or run \`source ~/.bashrc\` (Linux) or \`source ~/.zshrc\` (macOS)

**Problem:** "Permission denied" errors
**Solution:** Don't use sudo with npm. Fix permissions:
\`\`\`bash
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
\`\`\`

示例 2：Python 项目设置

## Setting Up Python Development Environment

### Step 1: Install Python

**macOS:**
\`\`\`bash
brew install [email protected]
\`\`\`

**Linux:**
\`\`\`bash
sudo apt update
sudo apt install python3.11 python3.11-venv python3-pip
\`\`\`

**Windows:**
\`\`\`powershell
choco install python --version=3.11
\`\`\`

### Step 2: Verify Installation

\`\`\`bash
python3 --version  # Should show Python 3.11.x
pip3 --version     # Should show pip 23.x.x
\`\`\`

### Step 3: Create Virtual Environment

\`\`\`bash
# Navigate to project directory
cd my-project

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
# macOS/Linux:
source venv/bin/activate

# Windows:
venv\Scripts\activate
\`\`\`

### Step 4: Install Dependencies

\`\`\`bash
# Install from requirements.txt
pip install -r requirements.txt

# Or install packages individually
pip install flask sqlalchemy python-dotenv
\`\`\`

### Step 5: Set Up Environment Variables

Create \`.env\` file:
\`\`\`
FLASK_APP=app.py
FLASK_ENV=development
DATABASE_URL=sqlite:///app.db
SECRET_KEY=your-secret-key-here
\`\`\`

### Step 6: Run the Application

\`\`\`bash
# Run Flask app
flask run

# Should see: Running on http://127.0.0.1:5000
\`\`\`

示例 3：Docker 开发环境

## Setting Up Docker Development Environment

### Step 1: Install Docker

**macOS:**
\`\`\`bash
brew install --cask docker
# Or download Docker Desktop from docker.com
\`\`\`

**Linux:**
\`\`\`bash
# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
cat get-docker.sh  # inspect the complete installer before execution
sudo sh get-docker.sh

# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker
\`\`\`

**Windows:**
Download Docker Desktop from docker.com

### Step 2: Verify Installation

\`\`\`bash
docker --version        # Should show Docker version 24.x.x
docker compose --version # Should show Docker Compose version 2.x.x
\`\`\`

### Step 3: Create docker compose.yml

\`\`\`yaml
version: '3.8'

services:
  app:
    build: .
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      - NODE_ENV=development
      - DATABASE_URL=postgresql://postgres:password@db:5432/mydb
    volumes:
      - .:/app
      - /app/node_modules
    depends_on:
      - db

  db:
    image: postgres:15
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=mydb
    ports:
      - "127.0.0.1:5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:
\`\`\`

### Step 4: Start Services

\`\`\`bash
# Build and start containers
docker compose up -d

# View logs
docker compose logs -f

# Stop services
docker compose down
\`\`\`

### Step 5: Verify Services

\`\`\`bash
# Check running containers
docker ps

# Test database connection
docker compose exec db psql -U postgres -d mydb
\`\`\`

最佳实践

✅ 请这样做

• 记录所有内容 - 编写清晰的设置说明
• 使用版本管理器 - Node.js 使用 nvm，Python 使用 pyenv
• 创建 .env.example - 展示所需的环境变量
• 在干净的系统上测试 - 验证说明是否适用于从零开始的环境
• 包含故障排查说明 - 记录常见问题及解决方法
• 使用 Docker - 确保不同设备上的环境一致
• 固定版本 - 在包文件中指定确切版本
• 自动化设置 - 尽可能创建设置脚本
• 检查先决条件 - 开始前列出所需工具
• 提供验证步骤 - 帮助用户确认设置是否正常

❌ 请勿这样做

• 不要假设工具已安装 - 始终进行检查并提供安装说明
• 不要遗漏环境变量 - 记录所有必需变量
• 不要对 npm 使用 Sudo - 应改为修复权限
• 不要忽视平台差异 - 提供针对不同操作系统的说明
• 不要省略验证步骤 - 始终包含测试步骤
• 不要全局安装 - 优先使用本地环境或虚拟环境
• 不要忽视错误 - 记录常见错误的处理方法
• 不要跳过数据库设置 - 包含数据库初始化步骤

常见陷阱

问题：“Command not found”（找不到命令）

**症状：**已安装工具，但终端无法识别 解决方案：

• 重启终端或加载 shell 配置
• 检查 PATH 环境变量
• 确认安装位置

# Check PATH
echo $PATH

# Add to PATH (example)
export PATH="/usr/local/bin:$PATH"

问题：npm/pip 权限错误

**症状：**出现 “EACCES” 或 “Permission denied” 错误 解决方案：

• 不要使用 sudo
• 修复 npm 权限或使用 nvm
• 为 Python 使用虚拟环境

# Fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc

问题：端口已被占用

症状：“Port 3000 is already in use”（端口 3000 已被占用） 解决方案：

• 找到并终止占用该端口的进程
• 使用其他端口

# Find process on port 3000
lsof -i :3000

# Kill process
kill -TERM <verified-owned-PID>

# Or use different port
PORT=3001 npm start

问题：数据库连接失败

**症状：**出现 “Connection refused”（连接被拒绝）或 “Authentication failed”（身份验证失败） 解决方案：

• 确认数据库正在运行
• 检查连接字符串
• 确认凭据

# Check if PostgreSQL is running
sudo systemctl status postgresql

# Test connection
psql -h localhost -U postgres -d mydb

设置脚本模板

创建 setup.sh 脚本以自动完成设置：

#!/bin/bash
set -euo pipefail
umask 077

echo "🚀 Setting up development environment..."

# Check prerequisites
command -v node >/dev/null 2>&1 || { echo "❌ Node.js not installed"; exit 1; }
command -v git >/dev/null 2>&1 || { echo "❌ Git not installed"; exit 1; }

echo "✅ Prerequisites check passed"

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

# Copy environment file
if [ ! -f .env ]; then
    echo "📝 Creating .env file..."
    cp .env.example .env
    echo "⚠️  Please edit .env with your configuration"
fi

 # Confirm a disposable/local database target before running this project-specific migration.
# Run database migrations
echo "🗄️  Running database migrations..."
npm run migrate

# Verify setup
echo "🔍 Verifying setup..."
npm run test:setup

echo "✅ Setup complete! Run 'npm run dev' to start"

相关技能

• @brainstorming - 在设置前规划环境要求
• @systematic-debugging - 调试环境问题
• @doc-coauthoring - 编写设置文档
• @git-pushing - 设置 Git 配置

其他资源

• Node.js 安装指南
• Python 虚拟环境
• Docker 文档
• Homebrew（macOS）
• Chocolatey（Windows）
• nvm（Node 版本管理器）
• pyenv（Python 版本管理器）

---

**专业提示：**创建 setup.sh 或 setup.ps1 脚本，以自动完成整个设置过程。在干净的系统上进行测试，确保脚本正常运行！

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为针对特定环境进行验证、测试或专家审查的替代品。
• 如果缺少必要的输入、权限、安全边界或成功标准，请暂停并请求澄清。