Environment Setup Guide

开发环境搭建指南

Overview

概述

Help developers set up complete development environments from scratch. This skill provides step-by-step guidance for installing tools, configuring dependencies, setting up environment variables, and verifying the setup works correctly.

帮助开发者从零开始搭建完整的开发环境。此技能提供分步指导，涵盖工具安装、依赖项配置、环境变量设置以及验证搭建是否正常工作等内容。

When to Use This Skill

何时使用此技能

Use when starting a new project and need to set up the development environment
Use when onboarding new team members to a project
Use when switching to a new machine or operating system
Use when troubleshooting environment-related issues
Use when documenting setup instructions for a project
Use when creating development environment documentation

启动新项目并需要搭建开发环境时使用
团队新成员加入项目进行入职培训时使用
更换新机器或操作系统时使用
排查与环境相关的问题时使用
为项目编写搭建说明文档时使用
创建开发环境相关文档时使用

How It Works

工作流程

Step 1: Identify Requirements

步骤1：确定需求

I'll help you determine what needs to be installed:

Programming language and version (Node.js, Python, Go, etc.)
Package managers (npm, pip, cargo, etc.)
Database systems (PostgreSQL, MongoDB, Redis, etc.)
Development tools (Git, Docker, IDE extensions, etc.)
Environment variables and configuration files

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

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

Step 2: Check Current Setup

步骤2：检查当前环境

Before installing anything, I'll help you check what's already installed:

bash

undefined

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

bash

undefined

Check versions of installed tools

node --version python --version git --version docker --version

undefined

node --version python --version git --version docker --version

undefined

Step 3: Provide Installation Instructions

步骤3：提供安装说明

I'll give platform-specific installation commands:

macOS: Using Homebrew
Linux: Using apt, yum, or package manager
Windows: Using Chocolatey, Scoop, or direct installers

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

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

Step 4: Configure the Environment

步骤4：配置环境

Help set up:

Environment variables (.env files)
Configuration files (.gitconfig, .npmrc, etc.)
IDE settings (VS Code, IntelliJ, etc.)
Shell configuration (.bashrc, .zshrc, etc.)

帮助完成以下配置：

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

Step 5: Verify Installation

步骤5：验证安装

Provide verification steps to ensure everything works:

Run version checks
Test basic commands
Verify database connections
Check environment variables are loaded

提供验证步骤以确保所有内容正常工作：

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

Examples

示例

Example 1: Node.js Project Setup

示例1：Node.js项目环境搭建

markdown

undefined

markdown

undefined

Setting Up Node.js Development Environment

Prerequisites

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

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

Step 1: Install Node.js

macOS (using Homebrew): ```bash

macOS (using Homebrew):

bash

undefined

Install Homebrew if not installed

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install Node.js

brew install node ```

Linux (Ubuntu/Debian): ```bash

brew install node


**Linux (Ubuntu/Debian):**
```bash

Update package list

sudo apt update

Install Node.js and npm

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs ```

Windows (using Chocolatey): ```powershell

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs


**Windows (using Chocolatey):**
```powershell

Install Chocolatey if not installed

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

Install Node.js

choco install nodejs ```

choco install nodejs

undefined

Step 2: Verify Installation

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

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

bash

undefined

Clone the repository

git clone https://github.com/your-repo/project.git cd project

Install dependencies

npm install ```

npm install

undefined

Step 4: Set Up Environment Variables

Create a `.env` file: ```bash

Create a

.env

file:

bash

undefined

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 ```

nano .env


Example `.env` content:

NODE_ENV=development PORT=3000 DATABASE_URL=postgresql://localhost:5432/mydb API_KEY=your-api-key-here

undefined

Step 5: Run the Project

```bash

bash

undefined

Start development server

npm run dev

Should see: Server running on http://localhost:3000

```

undefined

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 ```

undefined

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

undefined

Example 2: Python Project Setup

示例2：Python项目环境搭建

markdown

undefined

markdown

undefined

Setting Up Python Development Environment

Step 1: Install Python

macOS: ```bash brew install python@3.11 ```

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

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

macOS:

bash

brew install python@3.11

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 ```

bash

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

Step 3: Create Virtual Environment

```bash

bash

undefined

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 ```

venv\Scripts\activate

undefined

Step 4: Install Dependencies

```bash

bash

undefined

Install from requirements.txt

pip install -r requirements.txt

Or install packages individually

pip install flask sqlalchemy python-dotenv ```

pip install flask sqlalchemy python-dotenv

undefined

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 ```

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

bash

undefined

Run Flask app

flask run

Should see: Running on http://127.0.0.1:5000

```

undefined

undefined

Example 3: Docker Development Environment

示例3：Docker开发环境搭建

markdown

undefined

markdown

undefined

Setting Up Docker Development Environment

Step 1: Install Docker

macOS: ```bash brew install --cask docker

macOS:

bash

brew install --cask docker

Or download Docker Desktop from docker.com

```

Linux: ```bash


**Linux:**
```bash

Install Docker

curl -fsSL https://get.docker.com -o get-docker.sh sudo sh get-docker.sh

Add user to docker group

sudo usermod -aG docker $USER newgrp docker ```

Windows: Download Docker Desktop from docker.com

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 ```

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: - "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: - "5432:5432" volumes: - postgres_data:/var/lib/postgresql/data

volumes: postgres_data: ```

yaml

version: '3.8'

services:
  app:
    build: .
    ports:
      - "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:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

Step 4: Start Services

```bash

bash

undefined

Build and start containers

docker-compose up -d

View logs

docker-compose logs -f

Stop services

docker-compose down ```

docker-compose down

undefined

Step 5: Verify Services

```bash

bash

undefined

Check running containers

docker ps

Test database connection

docker-compose exec db psql -U postgres -d mydb ```

undefined

docker-compose exec db psql -U postgres -d mydb

undefined

Best Practices

最佳实践

✅ Do This

✅ 推荐做法

Document Everything - Write clear setup instructions
Use Version Managers - nvm for Node, pyenv for Python
Create .env.example - Show required environment variables
Test on Clean System - Verify instructions work from scratch
Include Troubleshooting - Document common issues and solutions
Use Docker - For consistent environments across machines
Pin Versions - Specify exact versions in package files
Automate Setup - Create setup scripts when possible
Check Prerequisites - List required tools before starting
Provide Verification Steps - Help users confirm setup works

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

❌ Don't Do This

❌ 不推荐做法

Don't Assume Tools Installed - Always check and provide install instructions
Don't Skip Environment Variables - Document all required variables
Don't Use Sudo with npm - Fix permissions instead
Don't Forget Platform Differences - Provide OS-specific instructions
Don't Leave Out Verification - Always include test steps
Don't Use Global Installs - Prefer local/virtual environments
Don't Ignore Errors - Document how to handle common errors
Don't Skip Database Setup - Include database initialization steps

不要假设工具已安装 - 始终检查并提供安装说明
不要忽略环境变量 - 记录所有必需的变量
不要对npm使用sudo - 改为修复权限问题
不要忽略平台差异 - 提供针对不同操作系统的说明
不要跳过验证步骤 - 始终包含测试环节
不要使用全局安装 - 优先选择本地/虚拟环境
不要忽略错误 - 记录如何处理常见错误
不要跳过数据库搭建 - 包含数据库初始化步骤

Common Pitfalls

常见陷阱

Problem: "Command not found" after installation

问题：安装后提示"Command not found"

Symptoms: Installed tool but terminal doesn't recognize it Solution:

Restart terminal or source shell config
Check PATH environment variable
Verify installation location

bash

undefined

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

重启终端或重新加载shell配置
检查PATH环境变量
验证安装位置

bash

undefined

Check PATH

echo $PATH

Add to PATH (example)

export PATH="/usr/local/bin:$PATH"

undefined

export PATH="/usr/local/bin:$PATH"

undefined

Problem: Permission errors with npm/pip

问题：npm/pip权限错误

Symptoms: "EACCES" or "Permission denied" errors Solution:

Don't use sudo
Fix npm permissions or use nvm
Use virtual environments for Python

bash

undefined

症状： 出现"EACCES"或"Permission denied"错误 解决方法：

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

bash

undefined

Fix npm permissions

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

undefined

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

undefined

Problem: Port already in use

问题：端口已被占用

Symptoms: "Port 3000 is already in use" Solution:

Find and kill process using the port
Use a different port

bash

undefined

症状： 提示"Port 3000 is already in use" 解决方法：

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

bash

undefined

Find process on port 3000

lsof -i :3000

Kill process

kill -9 <PID>

Or use different port

PORT=3001 npm start

undefined

PORT=3001 npm start

undefined

Problem: Database connection fails

问题：数据库连接失败

Symptoms: "Connection refused" or "Authentication failed" Solution:

Verify database is running
Check connection string
Verify credentials

bash

undefined

症状： 提示"Connection refused"或"Authentication failed" 解决方法：

验证数据库是否正在运行
检查连接字符串
验证凭据

bash

undefined

Check if PostgreSQL is running

sudo systemctl status postgresql

Test connection

psql -h localhost -U postgres -d mydb

undefined

psql -h localhost -U postgres -d mydb

undefined

Setup Script Template

搭建脚本模板

Create a

setup.sh

script to automate setup:

bash

#!/bin/bash

echo "🚀 Setting up development environment..."

创建

setup.sh

脚本以自动化搭建过程：

bash

#!/bin/bash

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"

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

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"

undefined

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

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

undefined

Related Skills

Additional Resources

额外资源

Pro Tip: Create a

setup.sh

or

setup.ps1

script to automate the entire setup process. Test it on a clean system to ensure it works!

专业提示： 创建

setup.sh

或

setup.ps1

脚本以自动化整个搭建过程。在干净系统上进行测试，确保脚本可以正常运行！

environment-setup-guide

Original

Translation

Environment Setup Guide

开发环境搭建指南

Overview

概述

When to Use This Skill

何时使用此技能

How It Works

工作流程

Step 1: Identify Requirements

步骤1：确定需求

Step 2: Check Current Setup

步骤2：检查当前环境

Check versions of installed tools

Check versions of installed tools

Step 3: Provide Installation Instructions

步骤3：提供安装说明

Step 4: Configure the Environment

步骤4：配置环境

Step 5: Verify Installation

步骤5：验证安装

Examples

示例

Example 1: Node.js Project Setup

示例1：Node.js项目环境搭建

Setting Up Node.js Development Environment

Setting Up Node.js Development Environment

Prerequisites

Prerequisites

Step 1: Install Node.js

Step 1: Install Node.js

Install Homebrew if not installed

Install Homebrew if not installed

Install Node.js

Install Node.js

Update package list

Update package list

Install Node.js and npm

Install Node.js and npm

Install Chocolatey if not installed

Install Chocolatey if not installed

Install Node.js

Install Node.js

Step 2: Verify Installation

Step 2: Verify Installation

Step 3: Install Project Dependencies

Step 3: Install Project Dependencies

Clone the repository

Clone the repository

Install dependencies

Install dependencies

Step 4: Set Up Environment Variables

Step 4: Set Up Environment Variables

Copy example environment file

Copy example environment file

Edit with your values

Edit with your values

Step 5: Run the Project

Step 5: Run the Project

Start development server

Start development server

Should see: Server running on http://localhost:3000

Should see: Server running on http://localhost:3000

Troubleshooting

Troubleshooting

Example 2: Python Project Setup

示例2：Python项目环境搭建

Setting Up Python Development Environment

Setting Up Python Development Environment

Step 1: Install Python

Step 1: Install Python

Step 2: Verify Installation

Step 2: Verify Installation

Step 3: Create Virtual Environment

Step 3: Create Virtual Environment

Navigate to project directory

Navigate to project directory

Create virtual environment