environment-setup-guide

用途

Environment Setup Guide 用于帮助开发者从零开始搭建完整的开发环境。它提供分步指导，涵盖安装工具、配置依赖、设置环境变量以及验证环境是否正常工作。

适用场景

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

主要能力

该技能按以下步骤工作：

识别需求：帮助确定需要安装的内容，包括编程语言及版本（Node.js、Python、Go 等）、包管理器（npm、pip、cargo 等）、数据库系统（PostgreSQL、MongoDB、Redis 等）、开发工具（Git、Docker、IDE 扩展等）、环境变量与配置文件。
检查当前环境：在安装前检查已安装的工具，例如通过 node --version、python --version、git --version、docker --version 等命令查看版本。
提供安装指令：给出针对不同平台的安装命令，macOS 使用 Homebrew，Linux 使用 apt、yum 或对应包管理器，Windows 使用 Chocolatey、Scoop 或直接安装程序。
配置环境：帮助设置环境变量（.env 文件）、配置文件（.gitconfig、.npmrc 等）、IDE 设置（VS Code、IntelliJ 等）、Shell 配置（.bashrc、.zshrc 等）。
验证安装：提供验证步骤，包括运行版本检查、测试基本命令、验证数据库连接、检查环境变量是否加载。

使用方式与示例

技能文档提供了三类示例：

Node.js 项目搭建：涵盖安装 Node.js（macOS 用 Homebrew、Linux 用 NodeSource 脚本、Windows 用 winget）、验证版本、安装项目依赖、创建 .env 文件、启动开发服务器，以及常见问题排查（如命令未找到、权限错误）。
Python 项目搭建：涵盖安装 Python 3.11、验证版本、创建虚拟环境、安装依赖、设置环境变量、运行 Flask 应用。
Docker 开发环境：涵盖安装 Docker、验证版本、编写 docker-compose.yml、启动服务、验证服务。

文档还提供了 setup.sh 脚本模板，用于自动化环境搭建流程，包括前置检查、安装依赖、复制环境文件、运行数据库迁移、验证设置等步骤。

最佳实践

文档建议：记录所有内容、使用版本管理器（nvm、pyenv）、创建 .env.example、在干净系统上测试、包含故障排查、使用 Docker 保持环境一致、固定版本、尽可能自动化、检查前置条件、提供验证步骤。同时提醒不要假设工具已安装、不要跳过环境变量、不要用 sudo 运行 npm、不要忽略平台差异、不要省略验证、不要使用全局安装、不要忽略错误、不要跳过数据库设置。

常见问题

文档列出了常见陷阱及解决方法，包括安装后“命令未找到”、npm/pip 权限错误、端口被占用、数据库连接失败等，并给出对应的排查命令与修复方式。

限制

仅在任务明确匹配上述范围时使用该技能。
不应将输出视为环境特定验证、测试或专家评审的替代。
如果缺少必要输入、权限、安全边界或成功标准，应停止并请求澄清。

技能介绍

用途