env-setup-assistant

环境配置助手技能

概述

此技能可帮助你创建可复现、方便开发者使用的环境。涵盖 IDE 配置、工具安装、依赖管理、入职文档和跨平台兼容性。

环境配置理念

原则

1. 一条命令完成配置：新开发者只需运行一条命令
2. 可复现：在任何地方都能获得相同的环境
3. 有文档说明：为边缘情况提供清晰说明
4. 版本固定：锁定工具和依赖版本

目标

• 应该：尽可能自动化所有工作
• 应该：尽早检测并报告问题
• 应该：支持多个平台（macOS、Linux、Windows）
• 不应该：假设已全局安装相关工具
• 不应该：要求执行没有文档说明的手动步骤

项目配置脚本

综合配置脚本

#!/bin/bash
# scripts/setup.sh

set -e  # Exit on error

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

log_info() { echo -e "${GREEN}[INFO]${NC} $1"; }
log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
log_error() { echo -e "${RED}[ERROR]${NC} $1"; }

# ===================
# Check Prerequisites
# ===================
check_command() {
    if ! command -v "$1" &> /dev/null; then
        log_error "$1 is not installed"
        return 1
    fi
    log_info "$1 found: $(command -v $1)"
    return 0
}

check_prerequisites() {
    log_info "Checking prerequisites..."

    local missing=0

    check_command "node" || missing=$((missing + 1))
    check_command "npm" || missing=$((missing + 1))
    check_command "git" || missing=$((missing + 1))

    # Check Node version
    local node_version=$(node -v | cut -d'v' -f2)
    local required_version="18.0.0"
    if ! [ "$(printf '%s\n' "$required_version" "$node_version" | sort -V | head -n1)" = "$required_version" ]; then
        log_error "Node.js version must be >= $required_version (found: $node_version)"
        missing=$((missing + 1))
    fi

    if [ $missing -gt 0 ]; then
        log_error "$missing prerequisite(s) missing"
        echo ""
        echo "Install missing tools:"
        echo "  - Node.js: https://nodejs.org/ or 'nvm install 20'"
        echo "  - Git: https://git-scm.com/"
        exit 1
    fi

    log_info "All prerequisites met!"
}

# ===================
# Environment Setup
# ===================
setup_env() {
    log_info "Setting up environment..."

    if [ ! -f .env ]; then
        if [ -f .env.example ]; then
            cp .env.example .env
            log_info "Created .env from .env.example"
            log_warn "Please update .env with your values"
        else
            log_error "No .env.example found"
            exit 1
        fi
    else
        log_info ".env already exists"
    fi
}

# ===================
# Install Dependencies
# ===================
install_dependencies() {
    log_info "Installing dependencies..."

    npm ci

    log_info "Dependencies installed!"
}

# ===================
# Setup Git Hooks
# ===================
setup_git_hooks() {
    log_info "Setting up Git hooks..."

    npx husky install 2>/dev/null || log_warn "Husky not configured"

    log_info "Git hooks configured!"
}

# ===================
# Database Setup
# ===================
setup_database() {
    log_info "Setting up database..."

    # Check if database is running
    if ! pg_isready -h localhost -p 5432 &>/dev/null; then
        log_warn "PostgreSQL not running on localhost:5432"
        log_info "Start with: docker-compose up -d db"
        return
    fi

    # Run migrations
    npm run db:migrate 2>/dev/null || log_warn "No migrations to run"

    # Seed data (development only)
    if [ "$NODE_ENV" != "production" ]; then
        npm run db:seed 2>/dev/null || log_warn "No seed script found"
    fi

    log_info "Database setup complete!"
}

# ===================
# Verify Setup
# ===================
verify_setup() {
    log_info "Verifying setup..."

    # Type check
    npm run typecheck 2>/dev/null && log_info "TypeScript: OK" || log_warn "TypeScript check failed"

    # Lint
    npm run lint 2>/dev/null && log_info "Linting: OK" || log_warn "Linting issues found"

    # Build test
    npm run build 2>/dev/null && log_info "Build: OK" || log_error "Build failed"
}

# ===================
# Main
# ===================
main() {
    echo ""
    echo "================================"
    echo "  Project Setup"
    echo "================================"
    echo ""

    check_prerequisites
    echo ""

    setup_env
    echo ""

    install_dependencies
    echo ""

    setup_git_hooks
    echo ""

    setup_database
    echo ""

    verify_setup
    echo ""

    echo "================================"
    echo "  Setup Complete!"
    echo "================================"
    echo ""
    echo "Next steps:"
    echo "  1. Update .env with your values"
    echo "  2. Start development: npm run dev"
    echo "  3. Open http://localhost:3000"
    echo ""
}

main "$@"

版本管理

.nvmrc / .node-version

20.10.0

工具版本（asdf）

# .tool-versions
nodejs 20.10.0
pnpm 8.12.0
python 3.11.6

Volta 配置

// package.json
{
  "volta": {
    "node": "20.10.0",
    "npm": "10.2.5"
  }
}

IDE 配置

VSCode 设置

// .vscode/settings.json
{
  // Editor
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit",
    "source.organizeImports": "explicit"
  },
  "editor.tabSize": 2,
  "editor.insertSpaces": true,
  "editor.rulers": [80, 120],

  // Files
  "files.trimTrailingWhitespace": true,
  "files.insertFinalNewline": true,
  "files.exclude": {
    "**/.git": true,
    "**/node_modules": true,
    "**/.next": true
  },

  // TypeScript
  "typescript.preferences.importModuleSpecifier": "relative",
  "typescript.updateImportsOnFileMove.enabled": "always",
  "typescript.tsdk": "node_modules/typescript/lib",

  // Tailwind
  "tailwindCSS.experimental.classRegex": [
    ["cva\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"],
    ["cn\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"]
  ],

  // ESLint
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact"
  ],

  // Prettier
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[typescriptreact]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[json]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

VSCode 扩展

// .vscode/extensions.json
{
  "recommendations": [
    // Essential
    "esbenp.prettier-vscode",
    "dbaeumer.vscode-eslint",
    "bradlc.vscode-tailwindcss",

    // TypeScript
    "ms-vscode.vscode-typescript-next",
    "yoavbls.pretty-ts-errors",

    // React/Next.js
    "dsznajder.es7-react-js-snippets",
    "formulahendry.auto-rename-tag",

    // Git
    "eamodio.gitlens",
    "mhutchie.git-graph",

    // Productivity
    "streetsidesoftware.code-spell-checker",
    "usernamehw.errorlens",
    "christian-kohler.path-intellisense",

    // Theme (optional)
    "GitHub.github-vscode-theme"
  ],
  "unwantedRecommendations": []
}

VSCode 启动配置

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug server-side",
      "type": "node",
      "request": "attach",
      "port": 9229,
      "skipFiles": ["<node_internals>/**"]
    },
    {
      "name": "Next.js: debug client-side",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:3000"
    },
    {
      "name": "Next.js: debug full stack",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/.bin/next",
      "args": ["dev"],
      "cwd": "${workspaceFolder}",
      "console": "integratedTerminal"
    },
    {
      "name": "Jest: current file",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/.bin/jest",
      "args": [
        "${fileBasename}",
        "--config",
        "jest.config.js",
        "--runInBand"
      ],
      "console": "integratedTerminal"
    }
  ]
}

EditorConfig

# .editorconfig
root = true

[*]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

[*.md]
trim_trailing_whitespace = false

[Makefile]
indent_style = tab

Git 配置

.gitattributes

# .gitattributes

# Auto detect text files
* text=auto eol=lf

# Documents
*.md text
*.txt text

# Source code
*.js text
*.jsx text
*.ts text
*.tsx text
*.css text
*.scss text
*.html text
*.json text
*.yaml text
*.yml text

# Docker
Dockerfile text

# Shell
*.sh text eol=lf

# Windows
*.bat text eol=crlf

# Binary
*.png binary
*.jpg binary
*.jpeg binary
*.gif binary
*.ico binary
*.woff binary
*.woff2 binary
*.ttf binary
*.eot binary
*.pdf binary

提交前钩子（Husky + lint-staged）

// package.json
{
  "scripts": {
    "prepare": "husky install"
  },
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{json,md,yml,yaml}": [
      "prettier --write"
    ]
  }
}

# .husky/pre-commit
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

npx lint-staged

# .husky/commit-msg
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

npx --no-install commitlint --edit "$1"

入职文档

CONTRIBUTING.md 模板

# Contributing Guide

## Getting Started

### Prerequisites

- Node.js 20+ ([install](https://nodejs.org/) or `nvm install 20`)
- pnpm 8+ (`npm install -g pnpm`)
- Docker Desktop ([install](https://docker.com/products/docker-desktop))
- Git ([install](https://git-scm.com/))

### Quick Start

```bash
# Clone the repository
git clone https://github.com/org/project.git
cd project

# Run setup script
./scripts/setup.sh

# Start development server
npm run dev

打开 http://localhost:3000

手动配置

如果配置脚本无法运行：

1. 安装依赖

   npm install
   

2. 设置环境

   cp .env.example .env
   # Edit .env with your values
   

3. 启动服务

   docker-compose up -d
   

4. 运行迁移

   npm run db:migrate
   

开发工作流

分支命名

• feature/description - 新功能
• fix/description - 修复错误
• chore/description - 维护工作
• docs/description - 文档

提交消息

我们使用 Conventional Commits：

type(scope): description

[optional body]

[optional footer]

类型：feat、fix、docs、style、refactor、test、chore

拉取请求

1. 从 main 创建分支
2. 进行更改
3. 运行测试：npm test
4. 运行代码检查：npm run lint
5. 创建针对 main 的 PR

可用脚本

命令	说明
npm run dev	启动开发服务器
npm run build	构建生产版本
npm run test	运行测试
npm run lint	运行代码检查
npm run typecheck	运行 TypeScript 检查

架构

[项目结构简要概述]

获取帮助

• 查看现有的问题
• 在 Slack 的 #dev-help 频道提问
• 联系 @maintainer

### Developer Onboarding Checklist

```markdown
# New Developer Onboarding

## Day 1 - Environment Setup

- [ ] Clone repository
- [ ] Run setup script
- [ ] Verify development server starts
- [ ] Install IDE extensions
- [ ] Join Slack channels: #dev, #dev-help

## Day 1 - Access

- [ ] GitHub repository access
- [ ] Vercel team access
- [ ] Supabase project access
- [ ] 1Password vault access
- [ ] Figma access

## Week 1 - Understanding

- [ ] Read CONTRIBUTING.md
- [ ] Review project architecture
- [ ] Complete starter task
- [ ] Pair with team member

## Helpful Links

- [Project Documentation](./docs/)
- [Design System](https://figma.com/...)
- [API Documentation](./docs/api/)

跨平台兼容性

平台检测脚本

# scripts/detect-platform.sh
#!/bin/bash

detect_os() {
    case "$(uname -s)" in
        Darwin)
            echo "macos"
            ;;
        Linux)
            echo "linux"
            ;;
        CYGWIN*|MINGW*|MSYS*)
            echo "windows"
            ;;
        *)
            echo "unknown"
            ;;
    esac
}

detect_arch() {
    case "$(uname -m)" in
        x86_64)
            echo "amd64"
            ;;
        arm64|aarch64)
            echo "arm64"
            ;;
        *)
            echo "unknown"
            ;;
    esac
}

OS=$(detect_os)
ARCH=$(detect_arch)

echo "Detected: $OS ($ARCH)"

Windows PowerShell 配置

# scripts/setup.ps1

Write-Host "Setting up development environment..." -ForegroundColor Green

# Check Node.js
if (-not (Get-Command node -ErrorAction SilentlyContinue)) {
    Write-Host "Node.js not found. Please install from https://nodejs.org/" -ForegroundColor Red
    exit 1
}

$nodeVersion = node -v
Write-Host "Node.js version: $nodeVersion" -ForegroundColor Cyan

# Copy environment file
if (-not (Test-Path .env)) {
    if (Test-Path .env.example) {
        Copy-Item .env.example .env
        Write-Host "Created .env from .env.example" -ForegroundColor Yellow
    }
}

# Install dependencies
Write-Host "Installing dependencies..." -ForegroundColor Green
npm ci

# Setup complete
Write-Host ""
Write-Host "Setup complete!" -ForegroundColor Green
Write-Host "Run 'npm run dev' to start development server" -ForegroundColor Cyan

环境检查清单

项目配置

• 配置脚本可在 macOS、Linux、Windows 上运行
• 记录前置条件及其版本
• 记录环境变量
• 已提交 IDE 配置
• 已配置 Git 钩子

开发者体验

• 一条命令完成配置
• 清晰的错误消息
• 入职文档
• 实用的 npm 脚本
• 调试配置

代码质量

• 已配置 ESLint
• 已配置 Prettier
• TypeScript 严格模式
• 提交前钩子
• 编辑器集成

何时使用此技能

在以下情况调用此技能：

• 启动新项目
• 帮助新开发者入职
• 统一团队环境
• 排查开发环境配置问题
• 创建配置自动化流程
• 配置 IDE 设置
• 设置跨平台开发环境