最近在带新人做前端项目时发现很多同学在第一步“环境搭建”上就卡住了。Git 和 Node.jsNPM是现代前端开发的基石版本不对、环境变量没配好后续的npm install、git clone每一步都可能报错非常影响学习效率和开发体验。网上的教程要么太旧要么只讲单一系统步骤零散不成体系。本文旨在提供一份Win10、Win11、macOS 三系统通用的 Git 和 Node.jsNPM安装与配置全攻略。我会从下载、安装、环境变量配置、基础命令验证一直讲到国内镜像加速等实用技巧。无论你是刚接触编程的新手还是需要在新电脑上快速配置环境的开发者跟着本文一步步操作都能搭建出一个稳定、高效的开发基础环境。1. 核心概念为什么需要 Git 和 Node.js在动手安装之前我们先花几分钟理解这两个工具的作用这能帮你更好地理解后续的配置步骤。1.1 Git代码的“时光机”与协作基石你可以把 Git 理解为一个超级强大的版本控制系统。想象一下你在写一份重要的文档每改一版都另存为一个新文件比如报告_v1.docx报告_v2_final.docx报告_v3_really_final.docx……很快就会混乱不堪。Git 解决了这个问题。核心功能版本管理记录项目文件每一次的修改谁、何时、改了哪里你可以随时回退到任何一个历史版本就像使用时光机。分支管理你可以创建代码的“平行宇宙”分支在新分支上开发新功能而不影响主线完成后再合并回去。这是团队协作和功能迭代的核心。远程仓库将代码备份/同步到云端如 GitHub、Gitee、GitLab实现多人协作开发。与 GitHub 的关系Git 是工具是一个安装在你自己电脑上的软件。GitHub 是一个网站提供了存放 Git 仓库的远程服务器。你可以用 Git 命令把本地代码推送到 GitHub。1.2 Node.js 与 NPMJavaScript 的“发动机”与“零件库”Node.js 和 NPM 是前端乃至全栈开发的运行引擎和生态管家。Node.js简单说它是一个能让 JavaScript 代码在电脑本地运行的环境。以前 JavaScript 只能跑在浏览器里Node.js 的出现让它具备了开发服务器、工具脚本等后端能力。我们安装它很多时候是为了获得这个“运行环境”。NPM全称 Node Package Manager即Node.js 包管理器。它是随 Node.js 一同安装的。前端项目依赖的成千上万个工具库如 React, Vue, Webpack, Axios 等都被称为“包”。NPM 的作用就是安装包一行命令npm install 包名就能下载和管理项目所需的所有依赖。管理项目通过package.json文件记录项目信息、依赖版本和脚本命令。发布分享你也可以将自己写的工具包发布到 NPM 供他人使用。总结Git 帮你管理代码历史和团队协作Node.js 和 NPM 为你提供项目运行环境和依赖管理能力。两者结合构成了现代 Web 开发的入门门槛。2. 环境准备与安装规划在开始安装前请确认你的操作系统。本文覆盖Windows 10/11和macOS两大平台。Linux 用户通常通过包管理器安装流程相对简单本文不赘述。核心原则安装路径建议使用默认路径或选择一个没有中文和空格的路径如D:\DevTools\。这可以避免很多潜在的兼容性问题。权限Windows 安装时如果弹出用户账户控制点击“是”macOS 可能需要输入密码。版本选择我们将选择长期支持版本以保证稳定性。3. Git 安装与配置详解3.1 Windows 系统安装 Git下载安装包 访问 Git 官网下载页https://git-scm.com/download/win。网站会自动推荐适合你系统位数64位的安装程序。下载Git-2.xx.x-64-bit.exe这样的文件。运行安装程序 双击安装包按照以下关键步骤进行配置许可协议直接Next。安装路径默认是C:\Program Files\Git\可以不改点Next。选择组件保持默认勾选即可Next。选择默认编辑器推荐选择Use Visual Studio Code as Git‘s default editor这样以后提交信息时会用 VSCode 打开。如果你没有安装 VSCode可以选Use the Nano editor by default或Use VimNext。调整 PATH 环境这是关键步骤选择Git from the command line and also from 3rd-party software。这个选项会将 Git 工具添加到系统的 PATH 环境变量中让你能在任何地方的命令行如 CMD、PowerShell中直接使用git命令。选择 HTTPS 传输后端保持默认Use the OpenSSL libraryNext。配置行尾符号转换选择Checkout Windows-style, commit Unix-style line endings。这是为了在 Windows 和 Unix/Linux 系统协作时保持兼容性Next。选择终端模拟器选择Use MinTTY (the default terminal of MSYS2)这个终端体验更好Next。其他选项后续步骤全部保持默认点击Install开始安装。验证安装 安装完成后在开始菜单找到Git-Git Bash打开一个黑底绿字的终端窗口。输入以下命令git --version如果显示类似git version 2.xx.x.windows.1的信息说明安装成功。3.2 macOS 系统安装 GitmacOS 通常预装了 Git但版本可能较旧。建议使用 Homebrew 安装或更新。方法一使用 Homebrew推荐如果你已经安装了 HomebrewmacOS 包管理器打开终端输入brew install git安装完成后用git --version验证。方法二下载安装包如果你没有 Homebrew可以访问 Git 官网下载 macOS 安装程序https://git-scm.com/download/mac。下载后双击.dmg文件将 Git 图标拖入Applications文件夹即可。3.3 首次使用 Git 的必要配置安装完成后需要在任何终端Windows 的 Git Bash 或 CMDmacOS 的终端里配置你的用户信息这是你提交代码时的“签名”。# 设置你的用户名通常使用GitHub/Gitee的用户名或英文名 git config --global user.name Your Name # 设置你的邮箱使用GitHub/Gitee注册邮箱 git config --global user.email your.emailexample.com # 可选让 Git 命令行输出带颜色更易读 git config --global color.ui auto # 查看所有配置确认信息已设置 git config --global --list4. Node.js 与 NPM 安装详解Node.js 的安装包已经包含了 NPM所以安装 Node.js 就等于安装了 NPM。4.1 Windows/macOS 通用使用安装包最简方式下载安装包 访问 Node.js 官网下载页https://nodejs.org/zh-cn/download/。强烈建议下载 LTS 版本LTS 代表“长期支持版”更稳定适合生产环境。Windows 用户下载.msi安装程序。macOS 用户下载.pkg安装程序。运行安装程序Windows双击.msi文件一路点击Next。在Custom Setup页面确保Node.js runtime、npm package manager和Add to PATH都被选中。这会将 Node.js 和 NPM 添加到系统环境变量。macOS双击.pkg文件根据安装向导提示操作需要输入密码。验证安装 安装完成后打开一个新的命令行窗口Windows 用 CMD 或 PowerShellmacOS 用终端分别输入以下命令node -v npm -v如果分别输出了 Node.js 的版本号如v18.xx.x和 NPM 的版本号如9.x.x则说明安装成功。4.2 macOS 进阶使用 Homebrew 安装如果你使用 Homebrew安装 Node.js 更简单且易于后续管理。# 安装 Node.js (会自动安装 npm) brew install node # 验证安装 node -v npm -v4.3 配置 NPM 国内镜像加速下载由于网络原因从 NPM 官方仓库下载包速度可能很慢。我们可以将其镜像地址切换到国内的淘宝镜像。# 设置淘宝镜像源 npm config set registry https://registry.npmmirror.com/ # 验证镜像是否设置成功 npm config get registry # 应该输出 https://registry.npmmirror.com/ # 可选安装 cnpm一个使用淘宝镜像的 npm 客户端 npm install -g cnpm --registryhttps://registry.npmmirror.com # 之后可以使用 cnpm install 代替 npm install速度更快5. 完整实战创建一个前端项目并关联 Git 仓库现在让我们用一个完整的例子串联起 Git 和 NPM 的基本工作流。5.1 初始化项目与 Git 仓库假设我们要在桌面创建一个名为my-first-project的 Vue.js 项目。打开终端并进入桌面# Windows (Git Bash 或 PowerShell) cd ~/Desktop # macOS cd ~/Desktop使用 Vue CLI 快速创建项目需要先全局安装vue/cli如果未安装可先运行npm install -g vue/clinpm create vuelatest my-first-project在创建向导中根据提示选择需要的特性如 TypeScript, Router, Pinia 等或直接一路回车使用默认选项。进入项目目录并初始化 Git 仓库cd my-first-project git init这会在项目根目录创建一个隐藏的.git文件夹标志着 Git 开始跟踪这个文件夹下的所有文件变更。进行第一次提交# 查看当前文件状态红色表示未跟踪的新文件 git status # 将所有文件添加到暂存区准备提交 git add . # 提交到本地仓库并附上提交信息 git commit -m initial commit: project scaffold created5.2 安装项目依赖并运行安装依赖 项目创建后查看package.json文件里面列出了项目需要的所有依赖包。运行以下命令安装它们npm install # 如果你配置了cnpm也可以用 cnpm installNPM 会读取package.json下载所有依赖包到node_modules文件夹。运行开发服务器 查看package.json中的scripts字段通常有一个dev或serve命令。运行它来启动项目npm run dev # 或 npm run serve终端会输出一个本地服务器地址通常是http://localhost:5173或http://localhost:3000。在浏览器中打开这个地址你就能看到刚刚创建的项目页面了。5.3 将本地仓库推送到远程以 Gitee 为例在 Gitee 上创建新仓库登录 Gitee点击“新建仓库”仓库名可以也叫my-first-project不要初始化README、.gitignore等文件。关联远程仓库 创建成功后Gitee 会给出仓库的 HTTPS 或 SSH 地址。在终端中执行# 将本地仓库与远程仓库关联your-repo-url 替换为 Gitee 提供的地址 git remote add origin https://gitee.com/your-username/my-first-project.git推送代码# 将本地的 master/main 分支推送到远程的 origin 仓库并建立追踪关系 git push -u origin master # 如果你的默认分支是 main则使用 git push -u origin main输入你的 Gitee 账号密码后代码就被推送到了云端。刷新 Gitee 仓库页面就能看到你的代码了。6. 常见问题与排查思路在安装和使用过程中你可能会遇到以下问题问题现象常见原因解决思路git或node不是内部或外部命令环境变量未正确配置。1. 检查安装时是否勾选了“Add to PATH”。2. 手动添加安装路径到系统环境变量PATH中。3.重启所有命令行窗口使环境变量生效。npm install速度极慢或失败网络连接 NPM 官方源不畅。1. 确认是否已配置淘宝镜像npm config get registry。2. 尝试使用cnpm安装。3. 检查网络代理设置。git push要求输入用户名密码且失败1. 远程地址是 HTTPS且密码认证已淘汰。2. 未配置 SSH 密钥。1.推荐配置 SSH 密钥对并添加到 Gitee/GitHub。然后使用 SSH 地址关联仓库 (gitxxx.git)。2. 临时方案使用个人访问令牌代替密码。项目运行报错提示依赖找不到node_modules损坏或版本不匹配。1. 删除项目下的node_modules文件夹和package-lock.json文件。2. 重新运行npm install。3. 检查package.json中依赖版本是否冲突。git commit时打开奇怪的编辑器如VimGit 的默认编辑器被设置成了 Vim。1. 退出 Vim按Esc然后输入:q!回车。2. 重新设置编辑器为 VSCodegit config --global core.editor code --wait。7. 最佳实践与工程建议Node.js 版本管理随着项目增多不同项目可能需要不同版本的 Node.js。建议使用nvm(Node Version Manager) 来管理多个 Node.js 版本可以轻松切换。Windows 用户可以使用nvm-windows。Git 提交规范提交信息commit message应清晰描述本次修改的内容。推荐使用约定式提交如feat: 添加用户登录功能、fix: 修复首页样式错位。避免使用update、fix bug等模糊描述。.gitignore文件项目初始化后第一件事就是创建或完善.gitignore文件。它告诉 Git 哪些文件不需要纳入版本管理如node_modules/,.env,dist/,*.log。这能保持仓库清洁避免提交无用的文件。依赖版本锁定package-lock.json或yarn.lock文件非常重要它锁定了所有依赖包的确切版本。务必将其提交到 Git 仓库以确保所有团队成员和线上部署环境安装的依赖版本完全一致。SSH 密钥配置为了安全便捷地使用 Git强烈建议配置 SSH 密钥替代 HTTPS 密码。只需在本地生成一次密钥对将公钥添加到 Gitee/GitHub之后所有操作都无需再输入密码。定期更新定期检查并更新 Git 和 Node.js 到新的稳定版本可以获取性能提升和安全补丁。但生产项目的 Node.js 版本升级需谨慎应在测试环境充分验证。至此你已经成功在 Windows 或 macOS 上搭建了 Git 和 Node.js 开发环境并掌握了从创建项目、管理依赖、版本控制到代码推送的完整基础工作流。这个环境是通往现代 Web 开发世界的大门后续学习任何前端框架React, Vue, Angular或 Node.js 后端开发都离不开它。