材料准备注意事项总结 新手必看避免踩坑
前两天有个刚入行的朋友来问我：”我照着网上的教程，把工具都装好了，一跑项目就报错，到底哪里出了问题？” 我翻了一下他的环境配置，好家伙，版本错乱、依赖冲突、路径里带中文，几乎踩了新手能踩的所有坑。
今天就把我这些年从项目里摸爬滚打总结出来的经验，一次性讲清楚。这篇不是那种”1234”的教科书式总结，更像是老人在旁边跟你唠嗑，希望能帮你少走点弯路。
先把方向想清楚，再动手准备
很多人一上来就狂装工具，装完才发现根本用不上，或者装的版本跟项目对不上。我见过最多的情况是：项目要求 Node.js 18，他装了个 20；Python 项目要求 3.9，他装了个 3.12，然后各种兼容性问题全来了。
所以第一步，先搞清楚你要做什么，再决定准备什么。
举几个常见的场景：
- 前端项目：Node.js 版本、包管理器（npm/yarn/pnpm 选一个，别混着用）、代码编辑器、版本控制工具
- 后端项目：运行时环境、数据库、Redis、消息队列、代码编辑器
- 数据分析/ML：Python 版本、虚拟环境工具、GPU 驱动（如果用 CUDA）
- 移动端开发：SDK、模拟器、签名证书
你可以先花 10 分钟，把项目的需求文档或 README 过一遍，把需要的环境列个清单。别急着动手，列完清单再对照检查。
版本管理：新手最大的坑
版本号这东西，看着简单，实际是新手踩坑的重灾区。
1. 同一个项目，永远不要混用多个版本
你电脑上可以同时装多个版本的 Node.js、Python、Java，但不要默认打开的终端里指向的是错的版本。
以 Node.js 为例，建议用 nvm（Node Version Manager）或者 fnm 来管理：
# 查看当前安装的 Node 版本
nvm list
# 切换到项目要求的版本
nvm use 18
# 设置默认版本（写进项目根目录的 .nvmrc 文件最稳妥）
echo "18.17.0" > .nvmrc
nvm use
Python 的话，推荐用 pyenv：
# 安装指定版本
pyenv install 3.9.18
# 切换到项目版本
pyenv local 3.9.18
一个小技巧：在项目根目录放一个 .nvmrc 或 .python-version 文件，这样换电脑或者别人拉代码的时候，nvm use 或 pyenv local 一下就直接对了，不用每次都手动查版本。
2. 别迷信”最新版就是最好的”
新项目可能用最新框架，但老项目往往绑定了特定版本。别自己给自己加戏，项目要求什么就用什么。
虚拟环境：必做，别偷懒
不管是什么技术栈，虚拟环境都是底线。我见过太多人把全局环境搞得一塌糊涂，后面排查问题能愁半年。
Node.js 项目
# 不要用全局装依赖，用项目级别的包管理
# 推荐 pnpm，速度快且磁盘占用小
pnpm install
# 或者用 npm
npm install
# 如果用 yarn
yarn install
Python 项目
# 创建虚拟环境（Python 3.3+ 内置 venv）
python -m venv .venv
# 激活虚拟环境
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate
# 安装依赖
pip install -r requirements.txt
# 推荐使用 pip-tools 或 poetry 管理依赖
pip-compile requirements.in # 锁定所有依赖版本
Go 项目
# Go modules 本身就是虚拟环境
go mod init myproject
go mod tidy
Java 项目
# Maven 项目
mvn dependency:resolve
# Gradle 项目
gradle dependencies
记住：虚拟环境的作用不只是隔离，更重要的是可复现。别人拿你的代码，pip install -r requirements.txt 或者 pnpm install 之后，跑出来的结果应该跟你一模一样。
路径和命名：别给未来的自己挖坑
这个点看着很小，但坑起来真要命。
项目路径不要有中文，不要有空格
❌ 错误示范：
C:\用户\张三\我的项目\前端开发\项目A
✅ 正确示范：
C:\projects\web-app\frontend
/home/user/projects/web-app/frontend
中文路径在 Linux 环境、Docker 容器、某些构建工具里经常出莫名其妙的问题，排查起来能让你怀疑人生。
避免使用过长的路径
Windows 系统对路径长度有限制（虽然 Win10 以后好多了，但还是建议简洁）。项目名也尽量简短有意义，frontend-app-v2-final-reallyfinal 这种名字以后维护的人想骂人。
依赖文件：别忽略 lock 文件
❌ 只传 package.json / requirements.txt
✅ 同时提交 package-lock.json / pnpm-lock.yaml / requirements.txt + pip-tools 的锁定文件
lock 文件的作用就是锁定依赖的精确版本。没有它，npm install 可能会拉到不同版本，导致”在我电脑上能跑，在你电脑上报错”的经典问题。
** Git 提交的时候，别忘记把 lock 文件也加进去。**
工具选型的几个原则
1. 社区活跃的优先
你选的框架、工具，GitHub Star 数、Issue 响应速度、更新频率都要看一眼。一个三年没更新的项目，踩了坑可能都找不到人问。
2. 文档完善度很重要
好的文档能让你少看十篇博客。遇到一个文档写得乱七八糟的工具，你花在排查上的时间可能是用好的工具的五倍。
3. 别追新，也别守旧
这个度有点难把握。我的建议是：
- 生产项目：用稳定版本，别当小白鼠
- 学习/练习项目：可以试试新的，但要有心理准备踩坑
- 团队项目：统一版本，别各玩各的
一个实用的检查清单
每次准备新环境之前，我习惯先过一遍这个清单：
- [ ] 运行环境版本确认（Node/Python/Java 等）
- [ ] 包管理器选定（npm/yarn/pnpm/pip 等）
- [ ] 虚拟环境创建并激活
- [ ] 依赖文件（lock 文件）齐全
- [ ] 项目路径无中文、无空格
- [ ] 代码编辑器已安装并配置好插件
- [ ] Git 已配置好（用户名、邮箱、SSH Key）
- [ ] 项目 .gitignore 已配置（别把 node_modules 提交进去）
- [ ] 本地环境变量配置好（.env 文件）
- [ ] 测试脚本能跑通（npm test / pytest 等）
最后说几句掏心窝的话
我带过几个新人，发现一个问题：越急越容易出错，越出错越慌。
遇到报错的第一反应别是去 Stack Overflow 复制粘贴，先看清楚报错信息。大多数时候，错误信息已经告诉了你问题在哪里，只是你没耐心读完。
比如这个常见的报错：
Error: EPERM: operation not permitted, open 'C:\Users\admin\project\node_modules\.staging\package.json'
一眼就能看出是路径里有中文或者权限问题，Windows 用户特别注意一下。
再比如 Python：
ModuleNotFoundError: No module named 'xxx'
先确认你激活的是哪个虚拟环境：
which python # macOS/Linux
where python # Windows
很多时候你以为是环境没装好，其实只是虚拟环境没激活，装的东西在另一个环境里。
材料准备这件事，看着琐碎，但做好了后面会顺很多。别想着一次性完美，先跑起来，遇到问题再解决，这才是正常的节奏。
有具体项目遇到问题的话，随时来问，别自己硬扛。