⚡

环境设置指南Skill environment-setup-guide

这个技能帮助开发者从零开始设置完整的开发环境，包括安装编程语言、包管理器、数据库系统、开发工具，配置环境变量、环境文件以及验证设置的正确性。适用于新项目启动、团队加入、环境切换等场景。关键词：开发环境设置、安装指南、环境配置、开发工具安装、DevOps、环境验证、设置文档。

DevOps 0 次安装 0 次浏览 更新于 3/21/2026

名称: 环境设置指南 描述: “指导开发者通过设置开发环境，配备适当的工具、依赖项和配置”

环境设置指南

概述

帮助开发者从零开始设置完整的开发环境。本技能提供逐步指导，包括安装工具、配置依赖项、设置环境变量以及验证设置是否正常工作。

何时使用此技能

  • 启动新项目并需要设置开发环境时使用
  • 新团队成员加入项目时使用
  • 切换到新机器或操作系统时使用
  • 排除环境相关问题时使用
  • 记录项目设置说明时使用
  • 创建开发环境文档时使用

工作原理

步骤1：识别需求

我会帮助您确定需要安装什么：

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

步骤2：检查当前设置

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

# 检查已安装工具的版本
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项目设置

## 设置Node.js开发环境

### 先决条件
- macOS、Linux或Windows
- 终端/命令提示符访问
- 互联网连接

### 步骤1：安装Node.js

**macOS（使用Homebrew）：**
\`\`\`bash
# 如果未安装Homebrew，则安装
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装Node.js
brew install node
\`\`\`

**Linux（Ubuntu/Debian）：**
\`\`\`bash
# 更新包列表
sudo apt update

# 安装Node.js和npm
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
\`\`\`

**Windows（使用Chocolatey）：**
\`\`\`powershell
# 如果未安装Chocolatey，则安装
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'))

# 安装Node.js
choco install nodejs
\`\`\`

### 步骤2：验证安装

\`\`\`bash
node --version  # 应显示v20.x.x或更高版本
npm --version   # 应显示10.x.x或更高版本
\`\`\`

### 步骤3：安装项目依赖项

\`\`\`bash
# 克隆仓库
git clone https://github.com/your-repo/project.git
cd project

# 安装依赖项
npm install
\`\`\`

### 步骤4：设置环境变量

创建\`.env\`文件：
\`\`\`bash
# 复制示例环境文件
cp .env.example .env

# 用您的值编辑
nano .env
\`\`\`

示例\`.env\`内容：
\`\`\`
NODE_ENV=development
PORT=3000
DATABASE_URL=postgresql://localhost:5432/mydb
API_KEY=your-api-key-here
\`\`\`

### 步骤5：运行项目

\`\`\`bash
# 启动开发服务器
npm run dev

# 应看到：服务器在http://localhost:3000上运行
\`\`\`

### 故障排除

**问题：** "node: 命令未找到"
**解决方案：** 重启终端或运行\`source ~/.bashrc\`（Linux）或\`source ~/.zshrc\`（macOS）

**问题：** "权限被拒绝"错误
**解决方案：** 不要使用sudo与npm。修复权限：
\`\`\`bash
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
\`\`\`

示例2：Python项目设置

## 设置Python开发环境

### 步骤1：安装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
\`\`\`

### 步骤2：验证安装

\`\`\`bash
python3 --version  # 应显示Python 3.11.x
pip3 --version     # 应显示pip 23.x.x
\`\`\`

### 步骤3：创建虚拟环境

\`\`\`bash
# 导航到项目目录
cd my-project

# 创建虚拟环境
python3 -m venv venv

# 激活虚拟环境
# macOS/Linux：
source venv/bin/activate

# Windows：
venv\Scripts\activate
\`\`\`

### 步骤4：安装依赖项

\`\`\`bash
# 从requirements.txt安装
pip install -r requirements.txt

# 或单独安装包
pip install flask sqlalchemy python-dotenv
\`\`\`

### 步骤5：设置环境变量

创建\`.env\`文件：
\`\`\`
FLASK_APP=app.py
FLASK_ENV=development
DATABASE_URL=sqlite:///app.db
SECRET_KEY=your-secret-key-here
\`\`\`

### 步骤6：运行应用程序

\`\`\`bash
# 运行Flask应用
flask run

# 应看到：在http://127.0.0.1:5000上运行
\`\`\`

示例3：Docker开发环境

## 设置Docker开发环境

### 步骤1：安装Docker

**macOS：**
\`\`\`bash
brew install --cask docker
# 或从docker.com下载Docker Desktop
\`\`\`

**Linux：**
\`\`\`bash
# 安装Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# 将用户添加到docker组
sudo usermod -aG docker $USER
newgrp docker
\`\`\`

**Windows：**
从docker.com下载Docker Desktop

### 步骤2：验证安装

\`\`\`bash
docker --version        # 应显示Docker版本24.x.x
docker-compose --version # 应显示Docker Compose版本2.x.x
\`\`\`

### 步骤3：创建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:
\`\`\`

### 步骤4：启动服务

\`\`\`bash
# 构建并启动容器
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down
\`\`\`

### 步骤5：验证服务

\`\`\`bash
# 检查运行中的容器
docker ps

# 测试数据库连接
docker-compose exec db psql -U postgres -d mydb
\`\`\`

最佳实践

✅ 这样做

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

❌ 不要这样做

  • 不要假设工具已安装 - 始终检查并提供安装说明
  • 不要跳过环境变量 - 记录所有必需变量
  • 不要与npm一起使用Sudo - 修复权限
  • 不要忘记平台差异 - 提供特定于操作系统的说明
  • 不要忽略验证 - 始终包含测试步骤
  • 不要使用全局安装 - 优先使用本地/虚拟环境
  • 不要忽略错误 - 记录如何处理常见错误
  • 不要跳过数据库设置 - 包括数据库初始化步骤

常见陷阱

问题：安装后"命令未找到"

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

  • 重启终端或source shell配置
  • 检查PATH环境变量
  • 验证安装位置
# 检查PATH
echo $PATH

# 添加到PATH（示例）
export PATH="/usr/local/bin:$PATH"

问题：npm/pip的权限错误

症状： "EACCES"或"权限被拒绝"错误 解决方案：

  • 不要使用sudo
  • 修复npm权限或使用nvm
  • 对Python使用虚拟环境
# 修复npm权限
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc

问题：端口已被使用

症状： “端口3000已被使用” 解决方案：

  • 查找并杀死使用该端口的进程
  • 使用不同的端口
# 查找端口3000上的进程
lsof -i :3000

# 杀死进程
kill -9 <PID>

# 或使用不同端口
PORT=3001 npm start

问题：数据库连接失败

症状： “连接被拒绝"或"认证失败” 解决方案：

  • 验证数据库是否在运行
  • 检查连接字符串
  • 验证凭据
# 检查PostgreSQL是否运行
sudo systemctl status postgresql

# 测试连接
psql -h localhost -U postgres -d mydb

设置脚本模板

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

#!/bin/bash

echo "🚀 设置开发环境..."

# 检查先决条件
command -v node >/dev/null 2>&1 || { echo "❌ Node.js未安装"; exit 1; }
command -v git >/dev/null 2>&1 || { echo "❌ Git未安装"; exit 1; }

echo "✅ 先决条件检查通过"

# 安装依赖项
echo "📦 安装依赖项..."
npm install

# 复制环境文件
if [ ! -f .env ]; then
    echo "📝 创建.env文件..."
    cp .env.example .env
    echo "⚠️  请用您的配置编辑.env"
fi

# 运行数据库迁移
echo "🗄️  运行数据库迁移..."
npm run migrate

# 验证设置
echo "🔍 验证设置..."
npm run test:setup

echo "✅ 设置完成！运行'npm run dev'以启动"

相关技能

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

额外资源

专业提示： 创建setup.sh或setup.ps1脚本以自动化整个设置过程。在干净系统上测试以确保它有效！