env-troubleshoot

环境排障（Env Troubleshoot）

环境问题的特点：每个人遇到的都不一样，但解决思路是一样的。核心方法是：读错误信息 → 定位问题类别 → 对症处理。

一、排障流程

环境报错后按以下步骤推进：

1. 读错误信息（完整读，不跳过）
2. 分类问题
3. 按类别排查
4. 修复并验证
5. 记录（如果是常见问题，建议加到项目 docs/guides/）

二、问题分类与排查

类别 1：依赖安装失败

常见错误特征、可能原因与排查步骤：

• ERESOLVE unable to resolve：npm 依赖版本冲突。排查：读冲突详情；npm ls <冲突包>；确定哪个依赖要求了不兼容版本。
• node-gyp rebuild FAILED：原生模块编译失败。排查：检查 node 版本；检查 Python/build-tools；macOS 上执行 xcode-select --install。
• EACCES permission denied：权限不足。排查：不要用 sudo 装 npm；检查 npm 全局目录权限；用 nvm 管理 node。
• network timeout：网络问题。排查：检查代理设置；切换镜像源 npm config set registry。
• ModuleNotFoundError（Python）：包未安装或虚拟环境未激活。排查：which python 确认解释器；检查 venv 是否激活；pip install -r requirements.txt。

类别 2：服务启动失败

• EADDRINUSE :::3000：端口被占用。排查：lsof -i :3000 找到占用进程，kill 或换端口。
• Error: Cannot find module：模块缺失。排查：rm -rf node_modules && npm install；检查路径拼写。
• ECONNREFUSED 127.0.0.1:5432：依赖服务未启动。排查：检查 DB/Redis 等依赖服务是否运行。
• 环境变量相关错误：.env 缺失或变量缺失。排查：cp .env.example .env；对照检查必填变量。
• SyntaxError: Unexpected token：Node/TS 版本不匹配。排查：检查 node -v 和 engines 字段，检查 tsconfig。

类别 3：Docker 问题

• Cannot connect to Docker daemon：Docker 未启动。排查：启动 Docker Desktop 或 systemctl start docker。
• no space left on device：磁盘/Docker 空间不足。排查：docker system prune 清理无用镜像和容器。
• COPY failed: file not found：Dockerfile 路径错误。排查：检查 COPY 源路径相对于 build context。
• 构建卡在某一层：网络问题或依赖下载慢。排查：检查 Docker 镜像源配置。
• 容器启动后立即退出：启动命令出错。排查：docker logs <container> 看日志。

类别 4：版本冲突

• Node.js 版本不对：node -v；检查 .nvmrc 或 engines；nvm use 切换。
• Python 版本不对：python --version；检查 pyproject.toml；用 pyenv 切换。
• TypeScript 编译错误：检查 tsconfig.json target；npx tsc --version。
• 全局工具版本冲突：which <tool> 确认用的哪个，必要时用 npx 跑项目本地版本。

类别 5：权限问题

• macOS 文件权限：ls -la 检查权限，chmod 修复。
• Git hook 没有执行权限：chmod +x .git/hooks/* 或 chmod +x .husky/*。
• SSH key 权限：chmod 600 ~/.ssh/id_*，chmod 700 ~/.ssh。

三、排障原则

• 先读错误信息：80% 的环境问题，错误信息本身就包含了答案。不要跳过错误信息直接猜。
• 从最简单的可能性开始：先检查服务是否启动、端口是否对、环境变量是否配了，再深入。
• 重现优先：如果用户描述的错误不完整，先复现问题再排查。
• 不要盲目清理：rm -rf node_modules 是最后手段，不是第一步。先理解为什么出错。
• 记录解法：如果是项目特有的环境问题，建议用户加到 docs/guides/ 或 README。

四、通用排查命令速查

Node.js 环境： node -v && npm -v # 版本检查 npm ls --depth=0 # 已安装依赖 npm cache clean --force # 清理缓存 npx envinfo # 环境信息汇总

Python 环境： python --version && pip --version which python # 确认解释器路径 pip list # 已安装包 python -m venv .venv && source .venv/bin/activate # 创建虚拟环境

端口/进程： lsof -i :3000 # 查端口占用 kill -9 <PID> # 杀进程

Docker： docker ps -a # 所有容器 docker logs <container> # 容器日志 docker system df # 磁盘占用 docker system prune # 清理

通用： echo $PATH # PATH 检查 env | grep -i proxy # 代理设置

五、适用场景与限制

适用场景：依赖安装失败、服务启动报错、Docker 起不来、端口被占、版本冲突、权限问题等开发环境排障。触发词包括装不上、跑不起来、报错了、环境问题、npm install 失败、Docker 起不来、端口被占。

限制：资料未提供该技能的安装方式、收费模式、支持平台及具体实现细节，暂未提供。