写这篇东西是因为最近团队里新来了几个小伙伴配置开发环境时遇到的问题一个接一个——版本对不上、命令找不到、代码提交后后悔想回退却不知道怎么操作。其实Git和Node.js是现在做开发几乎绕不开的两样东西一个是版本控制的事实标准一个是前端和工具链的运行时基石。这篇就把安装步骤和日常用得最多的命令整理出来按我的实际经验来写尽量让新手能照着走通老手也能查漏补缺。1. 先把底子打牢Git与Node.js到底是什么为什么必须装很多刚接触开发的同学容易把Git和Node.js混为一谈觉得它们都是“装完就能写代码”的东西。其实两者解决的问题完全不同。Git是一个分布式版本控制系统核心作用是追踪文件的变化。你可以把它理解成Word里的“历史版本”功能但强大得多——它能记录每一次修改、支持多人并行开发、随时回退到任意历史状态还能把代码同步到远程仓库进行协作。没有Git团队协作基本靠复制粘贴文件命名会变成“最终版”“最终版2”“真最终版”这种惨状在稍微正式一点的项目里是不可接受的。Node.js则是一个JavaScript运行时环境。传统上JavaScript只能在浏览器里跑Node.js把它带到了服务端和命令行工具领域。现在前端工程化几乎完全依赖Node.js生态像打包工具、代码检查工具、脚手架工具底层都是跑在Node.js上的。装好Node.js同时也带上了npmNode包管理器这是全球最大的开源软件包注册中心项目需要的各种依赖库都能通过npm一键安装。拿我自己的经历来说第一次用Git时觉得“不就是存个档吗”后来参与一个多人协作的项目分支合并的时候直接傻眼补了一晚上Git操作才算搞定。而Node.js的更替也经历过版本混乱、依赖装不上的痛苦。所以这篇把安装和命令放在一起讲是因为两者在实际开发中经常配合使用项目代码用Git管理项目依赖和脚本用npm管理先后装好、一起用好开发流程才算理顺。2. 安装环节最容易翻车的几个细节安装看似简单无非是下载、双击、下一步但实际踩坑的人不在少数。我先讲Git和Node.js各自怎么装再把最容易出问题的配置方法和版本管理讲透。2.1 Git安装与全局配置含Windows/macOS/LinuxGit在不同系统上的安装方式不太一样我按平台分别说。Windows用户直接去Git官网下载安装包选择对应位数的版本。安装过程中有几个关键选项要注意选择文本编辑器默认为Vim。如果你不熟悉Vim的操作建议选Notepad或VS Code不然后面提交代码时万一进到Vim界面会一头雾水。调整PATH环境变量务必选择“Git from the command line and also from 3rd-party software”这个选项这样才能在CMD、PowerShell以及各种IDE终端里直接使用Git命令。行结束符转换默认的Windows风格转换签出时转换CRLF、提交时转换LF一般保持默认即可适合大多数Windows场景。macOS用户最简单的方式是安装Xcode Command Line Tools在终端执行xcode-select --install即可系统会自动装好Git。也可以下载安装包或通过Homebrew安装brew install git。Linux用户直接用包管理器比如Ubuntu/Debian执行sudo apt install gitCentOS/RHEL执行sudo yum install git。装完Git第一件事不是急着用而是配置用户信息。因为Git的每一次提交都会记录作者这个信息必须设置否则提交会报错。配置命令如下git config --global user.name 你的名字 git config --global user.email 你的邮箱这两条命令把用户名和邮箱写在全局配置文件里之后这台机器上所有仓库的提交都会默认带上这些信息。想确认配置是否生效执行git config --global --list应该能看到刚才设置的两项。还有一些值得一改的配置项git config --global init.defaultBranch main git config --global core.autocrlf input git config --global color.ui trueinit.defaultBranch main是把默认分支名从master改为main这是近年来的主流实践。core.autocrlf input适合macOS/Linux用户避免Windows和Unix系统间换行符不一致引发的diff混乱。color.ui true让命令行下的输出带颜色查看diff和状态时肉眼识别更轻松。2.2 Node.js安装与版本切换重点讲nvm方案Node.js的安装看似简单但版本问题在真实开发中比想象中更棘手。老项目可能还在用12或14新项目已经要求18或20不同版本对某些依赖的兼容性差别很大。装一个版本用到底的做法风险不少所以我更推荐用版本管理器。Windows用户的选择比较务实有两个主流方案下载官方安装包安装固定版本简单直接适合只需要一个版本的情况。使用nvm-windowsNode Version Manager的Windows移植版支持在同一台机器上安装并随时切换多个Node.js版本。下载安装包后执行nvm install 18.19.0和nvm use 18.19.0就能完成切换。macOS/Linux用户直接用nvm脚本安装在终端执行curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash安装完成后重新打开终端执行nvm ls-remote查看所有可安装的版本列表然后nvm install --lts nvm use --lts--lts表示安装最新的长期支持版本稳定性优先不需要追新的话这个选择最稳妥。nvm ls可以看到本机装了哪些版本nvm alias default可以设置默认版本让每次新开终端都自动切到指定版本。如果实在不想用nvm官方安装包的“Download LTS”按钮是稳定选择的代名词下载安装后node -v能看到版本号就算大功告成。2.3 安装完成后的自检清单装完不等于配好了我一般会按这个清单逐项确认git --version node -v npm -v三条命令依次执行。git --version确认Git安装成功node -v和npm -v确认Node.js和npm都可用。如果提示“command not found”大概率是环境变量没配置好需要检查安装路径是否在PATH中。npm的配置往往被忽略但直接影响到下载依赖的速度。国内网络环境下npm默认源下载速度慢是出了名的体验痛点建议在终端执行npm config set registry https://registry.npmmirror.com把npm源切换到国内镜像下载速度会明显提升。执行npm config get registry确认当前源地址。3. Git日常高频命令实战从提交代码到撤销误操作装好Git之后真正的考验在于命令的熟练度。我按使用频率和逻辑顺序把日常命令拆开讲每条命令都结合实际场景说明而不是只列一个命令清单。3.1 初始化和第一笔提交进入项目目录执行git init把这个目录变成Git仓库。执行成功后会出现一个隐藏的.git目录所有版本信息都存在这里。git init git statusgit status是使用频率最高的命令查看当前工作区的状态——哪些文件被修改了、哪些还没被跟踪。刚init完的项目所有文件都会显示为未跟踪状态。提交第一笔代码前需要先了解Git的两个暂存概念工作区你实际编辑文件的地方。暂存区执行git add之后文件进入的区域相当于提交前的待发清单。提交流程共三步git add . git commit -m 初始提交初始化项目结构git add .把工作区所有改动加入暂存区。git commit -m带上提交说明创建一次提交。强调一下提交信息要写清楚这次改了什么不要写“update”“fix”这种看了等于没看的信息。团队协作中提交信息就是项目的历史文档。3.2 查看历史记录和文件变动明细想看项目的提交历史用git log。默认输出比较干巴巴我习惯用带格式参数的写法git log --oneline --graph --decorate -10这条命令用单行格式显示最近10条提交记录--graph画出分支结构图--decorate显示分支和标签指向。对快速了解项目进展帮助很大。想看某次提交具体改了什么文件用git showgit show commitIDcommitID就是git log里那串哈希值的前几位Git支持短哈希。git show默认展示这次提交的文件改动diff是代码审查的利器。如果只想看某两次提交之间的差异用git diffgit diff commitA commitB上面这条命令比较两个提交节点之间所有文件的变化。不加参数直接执行git diff查看的是工作区相对暂存区还有哪些未暂存的改动提交前检查这个命令非常实用。3.3 分支操作并行开发的基础能力分支是Git最核心的能力也是很多新手用了一段时间还是一知半解的部分。分支相当于从主时间线上拉出的平行世界两个开发者可以在不同分支上各改各的最后合并回来。git branch feature-login git branch第一条创建新分支feature-login第二条列出本仓库所有分支当前所在分支前会有星号标记。创建分支不等于切换分支真正切换要用git checkout feature-login新版Git也支持git switch feature-login作用和checkout一样但语义更清晰推荐使用。创建并切换一步完成的写法是git switch -c feature-login。切换分支前有个坑必须提醒如果有未提交的修改切换会导致这些修改“跟到”新分支上有时候会引发混乱。所以切换分支前最好把当前工作区弄干净——要么提交要么用stash暂存。git stash git switch feature-login git stash popgit stash把当前未提交的改动暂存到一个堆栈中切换完分支再git stash pop恢复是一个非常实用的组合操作。3.4 合并分支与解决冲突分支开发完成后把功能合并回主分支用git mergegit switch main git merge feature-login先切到要接收合并的分支再执行merge这样feature-login的内容会合并进main。Git如果发现两个分支修改了同一文件的同一处内容会报告冲突conflict此时文件会包含类似下面的标记 HEAD 这里是当前分支的内容 这里是被合并分支的内容 feature-login解决冲突的方法是打开文件手动保留正确的内容删除冲突标记和不要的部分然后重新提交git add 冲突文件 git commit -m 解决feature-login合并冲突冲突不是错误是Git保护代码的一种机制遇到时不用慌手动处理完提交即可。注意解决冲突时不要随手删掉另一个分支的所有修改先搞清两边的意图再决定保留哪部分。还有一个合并变体git merge --abort如果合并过程中发现处理不了这个命令可以取消合并让仓库回到merge前的状态。3.5 撤销操作覆盖and reset与checkout撤销操作是Git里最容易被误用的部分在团队协作场景里操作不当会引发事故。我按使用场景区分几种不同的“后悔药”。情况一刚刚提交了错误的内容但还没push到远程。合理做法是修改后重新提交用commit --amend覆盖上一次提交git commit --amend -m 修正后的提交信息这个命令把当前暂存区的改动和上一次提交合并成一个新的提交不会多出一条“修正”记录。注意如果该提交已经push到远程且别人已经拉取就不要再使用amend会引发历史冲突。情况二文件已暂存但想取消暂存用git reset HEAD 文件名这条命令把文件从暂存区移回工作区文件内容不受影响。情况三工作区文件被改坏了想恢复到上次提交的状态git checkout -- 文件名强制把工作区文件重置为最后一次提交的内容本地未提交的修改被全部覆盖。这个操作无法恢复执行前务必确认改动不要了。情况四想回退某次提交而不是直接删掉它。推荐用revertgit revert commitIDgit revert会生成一个新的提交这个新提交抹去了指定提交的内容但保留了历史记录多人协作场景下最安全因为所有操作都有迹可循。git reset的进阶用法是回退到指定提交git reset --hard commitID--hard参数会把工作区、暂存区、HEAD全部重置到指定提交之后的内容全部丢弃。单独在本地仓库使用可以接受但如果该提交已经push到远程操作前必须考虑其他人是否依赖了这个状态。3.6 远程仓库协同clone、push、pull与协作流程远程仓库是团队协作的中转站。本地仓库通过远程仓库关联到一起最常用的操作是把远程仓库克隆到本地git clone https://github.com/某组织/某项目.git执行后会在当前目录下生成一个和远程仓库同名的目录里面包含完整的Git历史和当前内容。克隆后进入目录git remote -v可以查看远程仓库地址。日常协作的循环是拉取最新代码、修改、提交、推送。git pull git pushgit pull会把远程的更新拉下来并自动合并到当前分支。git push把本地提交推送到远程。在多人协作仓库中严格遵循“先pull后push”的习惯能避免大量冲突。如果pull时有本地未提交的修改可能引发冲突所以pull前先git status看一眼比较稳妥。查看当前分支和远程的关系用git branch -vv这个命令会列出本地分支对应的远程跟踪分支及领先/落后的提交数。想拉取远程某个分支到本地并自动关联执行git switch -t origin/feature-abc如果确实不需要本地的某些修改想完全对齐远程可以在确认后执行git fetch origin然后git reset --hard origin/main但操作前必须确认本地没有需要保留的未提交工作。4. Node.js与npm常用命令解析从初始化项目到脚本管理Git管代码版本Node.js和npm管项目依赖与运行脚本。这一节讲清楚日常开发中必然用到的命令和背后的逻辑。4.1 项目初始化与package.json基础认知进入一个空目录执行npm init是每一个Node.js项目的起点npm init -y-y参数跳过交互式问答直接生成一份默认的package.json。这个文件是项目的“配置中心”记录项目名称、版本号、入口文件、依赖列表、脚本命令等关键信息。可以在文本编辑器中直接打开查看也可以随时修改。package.json的核心字段包括name项目名称发布到npm时必须全网唯一。version版本号语义化版本管理主版本.次版本.修订号。scripts脚本命令定义后续用npm run执行。dependencies生产环境依赖项目运行时需要的库。devDependencies开发环境依赖构建、测试等工具通常放在这里。在实际操作中生成后最好打开文件核对一下name、version字段确认无误再继续安装依赖。4.2 安装与管理依赖项目的依赖管理是npm最核心的功能。常用命令如下npm install 包名 npm install 包名 --save-dev npm install 包名版本号 npm install第一条安装生产依赖新版本npm默认写入dependencies。第二条安装开发依赖写入devDependencies适合安装测试框架、打包工具这类只在开发期使用的包。第三条安装指定版本比如npm install lodash4.17.21。第四条不带包名时npm会根据package.json里记录的依赖列表安装所有内容新clone下来的项目第一件事就是跑这条命令。依赖的概念有一个容易混淆的地方npm install安装一个包时包内部还依赖别的包这些间接依赖也会一并安装。所有装好的包存放在node_modules目录里这个目录体积很大通常不会被Git跟踪——这也是为什么新clone一个项目后第一件事是执行npm install而不是把node_modules也提交进版本库。package-lock.json是项目中的另一个重要文件它锁定了所有依赖的确切版本号。只要是npm install生成的lock文件都应该提交到Git仓库这样才能保证团队成员装出来的依赖版本完全一致。实际项目中的安装速度往往是一个痛点。除了前面配置镜像源还可以尝试用pnpm替代npm。pnpm是一款更高效的包管理器安装速度快、磁盘占用低它使用硬链接和内容寻址存储让多个项目共享同一份依赖文件。团队为了统一包管理器一般会在项目里保留一份package.json同时附加说明使用哪个包管理器。4.3 版本管理与常用查看命令依赖的版本管理要时刻清楚当前项目装了哪些包、处于什么版本。几条常用命令npm list npm list --depth0 npm view 包名 version npm outdatednpm list --depth0只显示直接依赖不展开间接依赖阅读体验最友好。npm view查看某个包在注册中心的最新版本装在本地与否都可以查。npm outdated会对比本地版本和最新版本列出有更新的包——升级依赖前先运行这条命令比盲目安装稳妥得多。更新某个依赖到最新版本用npm update 包名 npm install 包名latestnpm update在锁定版本范围内做小版本升级npm install 包名latest直接装上最新版本并写入package.json。4.4 运行脚本npm run的进阶用法package.json的scripts字段是项目自动化的主干。我举个例子一个常见项目的scripts配置如下scripts: { dev: vite, build: vue-tsc vite build, preview: vite preview, lint: eslint src --ext .js,.jsx,.ts,.tsx }运行方式统一是npm run 脚本名比如npm run dev启动开发服务器npm run build执行打包构建。npm run有一个特殊机制执行脚本时会把node_modules/.bin目录加入PATH所以scripts里可以直接写vite而不是../../../node_modules/.bin/vite——这个机制在理解脚本含义时很关键。两个常用技巧使用--向脚本传递参数比如npm run lint -- --fix会把--fix参数传给脚本内的命令。自定义脚本可以任意组合命令。比如scripts: { dev: node server.js, test: vitest run, start: node dist/index.js }很多新手在scripts里卡住的场景是本地跑正常的命令拿到线上就直接报错。经验是scripts里定义的命令应该尽量写在package.json里避免直接在终端手动复制粘贴一长串命令——脚本化管理能让全团队执行的操作保持一致。4.5 发布自己的包面向进阶读者如果你手上有工具函数库或组件库想分享给别人使用npm提供了完整的发布流程。首先确保完成npm官网账号注册然后在终端登录npm login在包目录下确认package.json的name和version设置正确然后执行npm publish发布前建议先检查包的内容用npm pack生成压缩包查看包含哪些文件。需要排除多余文件的场景在项目里配置.npmignore文件规则类似.gitignore。发布后发现版本号冲突会拒绝发布npm不允许覆盖已存在的版本号所以每次发布前必须修改version字段——常见做法是执行npm version patch/minor/major自动递增版本号。发布包的整个流程并不复杂难的是版本管理策略和文档维护这些是另一个话题这里先不展开。5. 高频报错与排查手册这些坑我基本都踩过安装和使用的过程中总会遇到各种报错有些错误信息看起来吓人实际原因很简单。我按场景整理一份排查手册。5.1 Git操作报错场景场景一提交时报错Please tell me who you are。原因很明确没有配置user.name和user.email。解决方法是执行前面讲的两条config命令。如果某个仓库想用和全局不同的身份进入该项目目录执行不带--global的配置命令这个配置只对当前仓库生效优先级高于全局配置。场景二执行git pull时提示error: You have not concluded your merge (MERGE_HEAD exists)。出现这个提示通常是因为上一次merge操作没完成或没处理干净。先查看当前状态git status确认是有未合并的文件还是遗留状态。如果不想继续合并执行git merge --abort取消合并并回到merge前状态。如果已经手动整合了一部分内容补齐文件后执行git add和git commit完成合并提交。场景三push被拒绝提示non-fast-forward。本地分支和远程分支历史分叉了远程有本地没有的提交。解决方法是先pull把远程的提交合并到本地处理冲突后再push。这条原则记好任何远程分支历史和别人分叉的情况下不要用git push --force强行推送除非你完全清楚自己在做什么。场景四误操作git reset --hard后发现提交没丢想找回来。Git在回收不可达对象之前那次提交还在。执行git reflog可以查看HEAD的历史移动记录找到丢失提交的commitID后执行git reset --hard commitID恢复到那个状态。这个命令是Git的急救工具但不要过度依赖正确的做法是重要操作前先确认或备份。5.2 命令找不到与环境变量问题场景一安装完成后执行node -v提示node is not recognizedWindows或command not foundUnix。几乎都是环境变量的问题。Windows用户在安装时勾选“Add to PATH”macOS/Linux用户需要检查nvm安装是否成功以及shell配置文件是否加载。重新打开终端往往就能解决。场景二npm能执行但node提示找不到。可能是npm和node安装路径分离的情况最常见的来源是Windows下某个项目自动安装的独立npm。确认的方式是执行where node和where npm看两个命令在不在同一个目录。不在的话修复方法多半是卸载多余的npm重新用统一方式安装。场景三macOS用户执行nvm提示找不到。nvm本身不是命令而是一个shell函数它定义在用户的shell配置文件中。确认 ~/.bashrc、~/.zshrc或~/.profile里是否已正确加载nvm的初始化脚本修改配置后执行source ~/.zshrc让配置生效。5.3 依赖安装相关报错场景一npm install报错EACCES permission denied。这是权限问题常见于用root用户安装了软件后又切回普通用户或者全局安装目录权限设置不当。解决方法是不要在系统全局目录直接安装依赖对社区常见的chmod处理方式我不推荐最稳妥是重新配置npm全局安装路径或者使用nvm这类版本管理器——用nvm安装的Node.js属于当前用户完全绕开全局权限问题。场景二安装一个包时提示ERESOLVE unable to resolve dependency tree。这是npm在解析依赖冲突时终止了安装。一般不应当盲目加--force或--legacy-peer-deps跳过先看报错信息里提到的冲突包名手动调整该包的版本或者确认一下是否真的要同时使用两个互相冲突的库版本。推荐先单独安装其中一个库npm install 包名 --legacy-peer-deps只是兜底方案并不是长久之计。场景三安装过程极慢或者直接超时。网络所限上文中配置镜像源是第一选择。改完后注意部分公司内部私有仓库需要独立配置源地址不同源间的切换用npm config set registry就能完成配合--registry参数可以在单条命令中临时指定源不改变全局配置npm install --registry https://registry.npmmirror.com场景四本地明明装了某个包但运行时直接报Cannot find module 包名。可能是包没有安装到当前项目的node_modules里或者包被安装到了全局而项目内找不到。处理思路是进入项目根目录执行npm list 包名确认依赖情况然后执行npm install 包名把依赖装进当前项目。6. 开发工作流实操记录一个真实项目的完整流程前面把命令拆开讲了但很多新手真正困惑的是“这些命令怎么连起来用”。下面我以一个模拟项目X的开发为背景把从零开始、到多人协作、再到发布的完整流程走一遍这个流程有很强的可复制性。项目起点某跨平台系统开发任务两个人协作主要需求是实现一个用户登录模块使用Express框架编写后端服务使用Git做版本管理。模块目录名定为user-login。流程第一步初始化本地仓库并创建基础文件cd user-login git init npm init -y第二步安装Express并生成入口代码npm install express touch index.jsindex.js写入一个最简单的服务const express require(express); const app express(); app.get(/, (req, res) res.send(User login service running)); app.listen(3000, () console.log(Server listening on port 3000));第三步第一次完整提交。这是整个流程中最应该养成习惯的动作代码不要堆到最后一次性提交一次提交对应一个逻辑功能后续用git log排查问题时才方便定位git add index.js package.json package-lock.json git commit -m 初始化项目并实现用户登录服务基础框架注意这一步我没有执行git add .把所有文件都加进去而是明确列出这次提交应包含的文件。有时候目录里会有一些不想提交的临时文件明确指定比无脑全都加更安全。第四步开发一个新功能用户注册接口。在index.js增加一个路由后执行git diff查看这次改动和之前的差异确认无误后再次提交git diff git add index.js git commit -m 新增用户注册路由第五步创建远程仓库并推送。在代码托管平台创建空仓库后把本地仓库和远程关联git remote add origin https://github.com/某组织/user-login.git git push -u origin main-u参数指定本次推送的分支为上游分支之后就可以直接执行git push和git pull不用每次写分支名。第六步模拟团队协作场景。假设同事A克隆了该仓库新建了一个功能分支做开发git clone https://github.com/某组织/user-login.git git switch -c feature-register开发完成后合并回主分支再推送git switch main git merge feature-register git push如果合并时出现冲突按3.4里的方法手动解决。这套流程建分支、开发、合回主分支、推送是绝大多数团队使用Git的标准模式熟练之后能适应各种协作方式。关于团队协作还有一个原则想特别强调不要直接在main分支上开发功能。哪怕是个人项目养成“开发分支做完再合回”的习惯能有效避免项目历史混乱。在实际的项目中主线分支通常是被保护的直接push会被拒绝必须通过合并请求的方式完成合并。7. 实操心得与一段时间的自省写到这里把最后几句经验留给你。这些东西不是文档里的标准答案是我自己踩坑后总结的。第一Git命令不需要死记硬背但git status和git log这两个命令必须形成肌肉记忆。不确定当前仓库什么状态时先跑git status不确定历史怎么发展的先跑git log --oneline --graph。所谓“不知道下一步用什么命令”排查的起点基本都是这两条。第二提交信息要当作正式的沟通文档来写。跟队友合作时一行清晰准确的提交说明能让代码审查的人少问十个问题。推荐的提交信息格式包括三部分做了什么动词开头为什么这么做影响了什么范围。例如“重构用户验证逻辑统一错误处理减少重复代码”就比“update stuff”有价值得多。第三Node.js版本管理有条件就用nvm。别嫌多此一举等到某个老项目因为Node版本太新而装不上依赖或者新项目因为Node版本太旧而报语法错误时你会明白一个能随手切换版本的工具有多省心。第四npm安装依赖之前先看看项目里是否有package-lock.json。有就在clone后直接npm ci这个命令严格按照lock文件安装依赖比npm install更快更干净也避免了lock文件被悄悄改动。我的习惯是CI环境和本地首次clone时用npm ci日常开发追加依赖时用npm install。第五配置镜像源这件事一旦换了环境要重新设置。接新电脑、换公司网络时第一件事不是写业务代码而是检查node版本、npm源和Git全局配置这三样确认好后面能省下大量碎片时间。我把这三步合称“新环境三件套”每次都按这个顺序过一遍基本不会再被环境问题卡住。Git和Node.js的学习曲线不算陡但也不像表面看起来那么平缓。真正见效的方式只有一个在真实项目里反复用用得多了就会自然记住那些命令和原理。这篇内容覆盖了绝大多数日常场景照着走完一个完整流程你就已经超过了相当一部分“会clone但不会处理冲突”的开发者。
写这篇东西是因为最近团队里新来了几个小伙伴配置开发环境时遇到的问题一个接一个——版本对不上、命令找不到、代码提交后后悔想回退却不知道怎么操作。其实Git和Node.js是现在做开发几乎绕不开的两样东西一个是版本控制的事实标准一个是前端和工具链的运行时基石。这篇就把安装步骤和日常用得最多的命令整理出来按我的实际经验来写尽量让新手能照着走通老手也能查漏补缺。1. 先把底子打牢Git与Node.js到底是什么为什么必须装很多刚接触开发的同学容易把Git和Node.js混为一谈觉得它们都是“装完就能写代码”的东西。其实两者解决的问题完全不同。Git是一个分布式版本控制系统核心作用是追踪文件的变化。你可以把它理解成Word里的“历史版本”功能但强大得多——它能记录每一次修改、支持多人并行开发、随时回退到任意历史状态还能把代码同步到远程仓库进行协作。没有Git团队协作基本靠复制粘贴文件命名会变成“最终版”“最终版2”“真最终版”这种惨状在稍微正式一点的项目里是不可接受的。Node.js则是一个JavaScript运行时环境。传统上JavaScript只能在浏览器里跑Node.js把它带到了服务端和命令行工具领域。现在前端工程化几乎完全依赖Node.js生态像打包工具、代码检查工具、脚手架工具底层都是跑在Node.js上的。装好Node.js同时也带上了npmNode包管理器这是全球最大的开源软件包注册中心项目需要的各种依赖库都能通过npm一键安装。拿我自己的经历来说第一次用Git时觉得“不就是存个档吗”后来参与一个多人协作的项目分支合并的时候直接傻眼补了一晚上Git操作才算搞定。而Node.js的更替也经历过版本混乱、依赖装不上的痛苦。所以这篇把安装和命令放在一起讲是因为两者在实际开发中经常配合使用项目代码用Git管理项目依赖和脚本用npm管理先后装好、一起用好开发流程才算理顺。2. 安装环节最容易翻车的几个细节安装看似简单无非是下载、双击、下一步但实际踩坑的人不在少数。我先讲Git和Node.js各自怎么装再把最容易出问题的配置方法和版本管理讲透。2.1 Git安装与全局配置含Windows/macOS/LinuxGit在不同系统上的安装方式不太一样我按平台分别说。Windows用户直接去Git官网下载安装包选择对应位数的版本。安装过程中有几个关键选项要注意选择文本编辑器默认为Vim。如果你不熟悉Vim的操作建议选Notepad或VS Code不然后面提交代码时万一进到Vim界面会一头雾水。调整PATH环境变量务必选择“Git from the command line and also from 3rd-party software”这个选项这样才能在CMD、PowerShell以及各种IDE终端里直接使用Git命令。行结束符转换默认的Windows风格转换签出时转换CRLF、提交时转换LF一般保持默认即可适合大多数Windows场景。macOS用户最简单的方式是安装Xcode Command Line Tools在终端执行xcode-select --install即可系统会自动装好Git。也可以下载安装包或通过Homebrew安装brew install git。Linux用户直接用包管理器比如Ubuntu/Debian执行sudo apt install gitCentOS/RHEL执行sudo yum install git。装完Git第一件事不是急着用而是配置用户信息。因为Git的每一次提交都会记录作者这个信息必须设置否则提交会报错。配置命令如下git config --global user.name 你的名字 git config --global user.email 你的邮箱这两条命令把用户名和邮箱写在全局配置文件里之后这台机器上所有仓库的提交都会默认带上这些信息。想确认配置是否生效执行git config --global --list应该能看到刚才设置的两项。还有一些值得一改的配置项git config --global init.defaultBranch main git config --global core.autocrlf input git config --global color.ui trueinit.defaultBranch main是把默认分支名从master改为main这是近年来的主流实践。core.autocrlf input适合macOS/Linux用户避免Windows和Unix系统间换行符不一致引发的diff混乱。color.ui true让命令行下的输出带颜色查看diff和状态时肉眼识别更轻松。2.2 Node.js安装与版本切换重点讲nvm方案Node.js的安装看似简单但版本问题在真实开发中比想象中更棘手。老项目可能还在用12或14新项目已经要求18或20不同版本对某些依赖的兼容性差别很大。装一个版本用到底的做法风险不少所以我更推荐用版本管理器。Windows用户的选择比较务实有两个主流方案下载官方安装包安装固定版本简单直接适合只需要一个版本的情况。使用nvm-windowsNode Version Manager的Windows移植版支持在同一台机器上安装并随时切换多个Node.js版本。下载安装包后执行nvm install 18.19.0和nvm use 18.19.0就能完成切换。macOS/Linux用户直接用nvm脚本安装在终端执行curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash安装完成后重新打开终端执行nvm ls-remote查看所有可安装的版本列表然后nvm install --lts nvm use --lts--lts表示安装最新的长期支持版本稳定性优先不需要追新的话这个选择最稳妥。nvm ls可以看到本机装了哪些版本nvm alias default可以设置默认版本让每次新开终端都自动切到指定版本。如果实在不想用nvm官方安装包的“Download LTS”按钮是稳定选择的代名词下载安装后node -v能看到版本号就算大功告成。2.3 安装完成后的自检清单装完不等于配好了我一般会按这个清单逐项确认git --version node -v npm -v三条命令依次执行。git --version确认Git安装成功node -v和npm -v确认Node.js和npm都可用。如果提示“command not found”大概率是环境变量没配置好需要检查安装路径是否在PATH中。npm的配置往往被忽略但直接影响到下载依赖的速度。国内网络环境下npm默认源下载速度慢是出了名的体验痛点建议在终端执行npm config set registry https://registry.npmmirror.com把npm源切换到国内镜像下载速度会明显提升。执行npm config get registry确认当前源地址。3. Git日常高频命令实战从提交代码到撤销误操作装好Git之后真正的考验在于命令的熟练度。我按使用频率和逻辑顺序把日常命令拆开讲每条命令都结合实际场景说明而不是只列一个命令清单。3.1 初始化和第一笔提交进入项目目录执行git init把这个目录变成Git仓库。执行成功后会出现一个隐藏的.git目录所有版本信息都存在这里。git init git statusgit status是使用频率最高的命令查看当前工作区的状态——哪些文件被修改了、哪些还没被跟踪。刚init完的项目所有文件都会显示为未跟踪状态。提交第一笔代码前需要先了解Git的两个暂存概念工作区你实际编辑文件的地方。暂存区执行git add之后文件进入的区域相当于提交前的待发清单。提交流程共三步git add . git commit -m 初始提交初始化项目结构git add .把工作区所有改动加入暂存区。git commit -m带上提交说明创建一次提交。强调一下提交信息要写清楚这次改了什么不要写“update”“fix”这种看了等于没看的信息。团队协作中提交信息就是项目的历史文档。3.2 查看历史记录和文件变动明细想看项目的提交历史用git log。默认输出比较干巴巴我习惯用带格式参数的写法git log --oneline --graph --decorate -10这条命令用单行格式显示最近10条提交记录--graph画出分支结构图--decorate显示分支和标签指向。对快速了解项目进展帮助很大。想看某次提交具体改了什么文件用git showgit show commitIDcommitID就是git log里那串哈希值的前几位Git支持短哈希。git show默认展示这次提交的文件改动diff是代码审查的利器。如果只想看某两次提交之间的差异用git diffgit diff commitA commitB上面这条命令比较两个提交节点之间所有文件的变化。不加参数直接执行git diff查看的是工作区相对暂存区还有哪些未暂存的改动提交前检查这个命令非常实用。3.3 分支操作并行开发的基础能力分支是Git最核心的能力也是很多新手用了一段时间还是一知半解的部分。分支相当于从主时间线上拉出的平行世界两个开发者可以在不同分支上各改各的最后合并回来。git branch feature-login git branch第一条创建新分支feature-login第二条列出本仓库所有分支当前所在分支前会有星号标记。创建分支不等于切换分支真正切换要用git checkout feature-login新版Git也支持git switch feature-login作用和checkout一样但语义更清晰推荐使用。创建并切换一步完成的写法是git switch -c feature-login。切换分支前有个坑必须提醒如果有未提交的修改切换会导致这些修改“跟到”新分支上有时候会引发混乱。所以切换分支前最好把当前工作区弄干净——要么提交要么用stash暂存。git stash git switch feature-login git stash popgit stash把当前未提交的改动暂存到一个堆栈中切换完分支再git stash pop恢复是一个非常实用的组合操作。3.4 合并分支与解决冲突分支开发完成后把功能合并回主分支用git mergegit switch main git merge feature-login先切到要接收合并的分支再执行merge这样feature-login的内容会合并进main。Git如果发现两个分支修改了同一文件的同一处内容会报告冲突conflict此时文件会包含类似下面的标记 HEAD 这里是当前分支的内容 这里是被合并分支的内容 feature-login解决冲突的方法是打开文件手动保留正确的内容删除冲突标记和不要的部分然后重新提交git add 冲突文件 git commit -m 解决feature-login合并冲突冲突不是错误是Git保护代码的一种机制遇到时不用慌手动处理完提交即可。注意解决冲突时不要随手删掉另一个分支的所有修改先搞清两边的意图再决定保留哪部分。还有一个合并变体git merge --abort如果合并过程中发现处理不了这个命令可以取消合并让仓库回到merge前的状态。3.5 撤销操作覆盖and reset与checkout撤销操作是Git里最容易被误用的部分在团队协作场景里操作不当会引发事故。我按使用场景区分几种不同的“后悔药”。情况一刚刚提交了错误的内容但还没push到远程。合理做法是修改后重新提交用commit --amend覆盖上一次提交git commit --amend -m 修正后的提交信息这个命令把当前暂存区的改动和上一次提交合并成一个新的提交不会多出一条“修正”记录。注意如果该提交已经push到远程且别人已经拉取就不要再使用amend会引发历史冲突。情况二文件已暂存但想取消暂存用git reset HEAD 文件名这条命令把文件从暂存区移回工作区文件内容不受影响。情况三工作区文件被改坏了想恢复到上次提交的状态git checkout -- 文件名强制把工作区文件重置为最后一次提交的内容本地未提交的修改被全部覆盖。这个操作无法恢复执行前务必确认改动不要了。情况四想回退某次提交而不是直接删掉它。推荐用revertgit revert commitIDgit revert会生成一个新的提交这个新提交抹去了指定提交的内容但保留了历史记录多人协作场景下最安全因为所有操作都有迹可循。git reset的进阶用法是回退到指定提交git reset --hard commitID--hard参数会把工作区、暂存区、HEAD全部重置到指定提交之后的内容全部丢弃。单独在本地仓库使用可以接受但如果该提交已经push到远程操作前必须考虑其他人是否依赖了这个状态。3.6 远程仓库协同clone、push、pull与协作流程远程仓库是团队协作的中转站。本地仓库通过远程仓库关联到一起最常用的操作是把远程仓库克隆到本地git clone https://github.com/某组织/某项目.git执行后会在当前目录下生成一个和远程仓库同名的目录里面包含完整的Git历史和当前内容。克隆后进入目录git remote -v可以查看远程仓库地址。日常协作的循环是拉取最新代码、修改、提交、推送。git pull git pushgit pull会把远程的更新拉下来并自动合并到当前分支。git push把本地提交推送到远程。在多人协作仓库中严格遵循“先pull后push”的习惯能避免大量冲突。如果pull时有本地未提交的修改可能引发冲突所以pull前先git status看一眼比较稳妥。查看当前分支和远程的关系用git branch -vv这个命令会列出本地分支对应的远程跟踪分支及领先/落后的提交数。想拉取远程某个分支到本地并自动关联执行git switch -t origin/feature-abc如果确实不需要本地的某些修改想完全对齐远程可以在确认后执行git fetch origin然后git reset --hard origin/main但操作前必须确认本地没有需要保留的未提交工作。4. Node.js与npm常用命令解析从初始化项目到脚本管理Git管代码版本Node.js和npm管项目依赖与运行脚本。这一节讲清楚日常开发中必然用到的命令和背后的逻辑。4.1 项目初始化与package.json基础认知进入一个空目录执行npm init是每一个Node.js项目的起点npm init -y-y参数跳过交互式问答直接生成一份默认的package.json。这个文件是项目的“配置中心”记录项目名称、版本号、入口文件、依赖列表、脚本命令等关键信息。可以在文本编辑器中直接打开查看也可以随时修改。package.json的核心字段包括name项目名称发布到npm时必须全网唯一。version版本号语义化版本管理主版本.次版本.修订号。scripts脚本命令定义后续用npm run执行。dependencies生产环境依赖项目运行时需要的库。devDependencies开发环境依赖构建、测试等工具通常放在这里。在实际操作中生成后最好打开文件核对一下name、version字段确认无误再继续安装依赖。4.2 安装与管理依赖项目的依赖管理是npm最核心的功能。常用命令如下npm install 包名 npm install 包名 --save-dev npm install 包名版本号 npm install第一条安装生产依赖新版本npm默认写入dependencies。第二条安装开发依赖写入devDependencies适合安装测试框架、打包工具这类只在开发期使用的包。第三条安装指定版本比如npm install lodash4.17.21。第四条不带包名时npm会根据package.json里记录的依赖列表安装所有内容新clone下来的项目第一件事就是跑这条命令。依赖的概念有一个容易混淆的地方npm install安装一个包时包内部还依赖别的包这些间接依赖也会一并安装。所有装好的包存放在node_modules目录里这个目录体积很大通常不会被Git跟踪——这也是为什么新clone一个项目后第一件事是执行npm install而不是把node_modules也提交进版本库。package-lock.json是项目中的另一个重要文件它锁定了所有依赖的确切版本号。只要是npm install生成的lock文件都应该提交到Git仓库这样才能保证团队成员装出来的依赖版本完全一致。实际项目中的安装速度往往是一个痛点。除了前面配置镜像源还可以尝试用pnpm替代npm。pnpm是一款更高效的包管理器安装速度快、磁盘占用低它使用硬链接和内容寻址存储让多个项目共享同一份依赖文件。团队为了统一包管理器一般会在项目里保留一份package.json同时附加说明使用哪个包管理器。4.3 版本管理与常用查看命令依赖的版本管理要时刻清楚当前项目装了哪些包、处于什么版本。几条常用命令npm list npm list --depth0 npm view 包名 version npm outdatednpm list --depth0只显示直接依赖不展开间接依赖阅读体验最友好。npm view查看某个包在注册中心的最新版本装在本地与否都可以查。npm outdated会对比本地版本和最新版本列出有更新的包——升级依赖前先运行这条命令比盲目安装稳妥得多。更新某个依赖到最新版本用npm update 包名 npm install 包名latestnpm update在锁定版本范围内做小版本升级npm install 包名latest直接装上最新版本并写入package.json。4.4 运行脚本npm run的进阶用法package.json的scripts字段是项目自动化的主干。我举个例子一个常见项目的scripts配置如下scripts: { dev: vite, build: vue-tsc vite build, preview: vite preview, lint: eslint src --ext .js,.jsx,.ts,.tsx }运行方式统一是npm run 脚本名比如npm run dev启动开发服务器npm run build执行打包构建。npm run有一个特殊机制执行脚本时会把node_modules/.bin目录加入PATH所以scripts里可以直接写vite而不是../../../node_modules/.bin/vite——这个机制在理解脚本含义时很关键。两个常用技巧使用--向脚本传递参数比如npm run lint -- --fix会把--fix参数传给脚本内的命令。自定义脚本可以任意组合命令。比如scripts: { dev: node server.js, test: vitest run, start: node dist/index.js }很多新手在scripts里卡住的场景是本地跑正常的命令拿到线上就直接报错。经验是scripts里定义的命令应该尽量写在package.json里避免直接在终端手动复制粘贴一长串命令——脚本化管理能让全团队执行的操作保持一致。4.5 发布自己的包面向进阶读者如果你手上有工具函数库或组件库想分享给别人使用npm提供了完整的发布流程。首先确保完成npm官网账号注册然后在终端登录npm login在包目录下确认package.json的name和version设置正确然后执行npm publish发布前建议先检查包的内容用npm pack生成压缩包查看包含哪些文件。需要排除多余文件的场景在项目里配置.npmignore文件规则类似.gitignore。发布后发现版本号冲突会拒绝发布npm不允许覆盖已存在的版本号所以每次发布前必须修改version字段——常见做法是执行npm version patch/minor/major自动递增版本号。发布包的整个流程并不复杂难的是版本管理策略和文档维护这些是另一个话题这里先不展开。5. 高频报错与排查手册这些坑我基本都踩过安装和使用的过程中总会遇到各种报错有些错误信息看起来吓人实际原因很简单。我按场景整理一份排查手册。5.1 Git操作报错场景场景一提交时报错Please tell me who you are。原因很明确没有配置user.name和user.email。解决方法是执行前面讲的两条config命令。如果某个仓库想用和全局不同的身份进入该项目目录执行不带--global的配置命令这个配置只对当前仓库生效优先级高于全局配置。场景二执行git pull时提示error: You have not concluded your merge (MERGE_HEAD exists)。出现这个提示通常是因为上一次merge操作没完成或没处理干净。先查看当前状态git status确认是有未合并的文件还是遗留状态。如果不想继续合并执行git merge --abort取消合并并回到merge前状态。如果已经手动整合了一部分内容补齐文件后执行git add和git commit完成合并提交。场景三push被拒绝提示non-fast-forward。本地分支和远程分支历史分叉了远程有本地没有的提交。解决方法是先pull把远程的提交合并到本地处理冲突后再push。这条原则记好任何远程分支历史和别人分叉的情况下不要用git push --force强行推送除非你完全清楚自己在做什么。场景四误操作git reset --hard后发现提交没丢想找回来。Git在回收不可达对象之前那次提交还在。执行git reflog可以查看HEAD的历史移动记录找到丢失提交的commitID后执行git reset --hard commitID恢复到那个状态。这个命令是Git的急救工具但不要过度依赖正确的做法是重要操作前先确认或备份。5.2 命令找不到与环境变量问题场景一安装完成后执行node -v提示node is not recognizedWindows或command not foundUnix。几乎都是环境变量的问题。Windows用户在安装时勾选“Add to PATH”macOS/Linux用户需要检查nvm安装是否成功以及shell配置文件是否加载。重新打开终端往往就能解决。场景二npm能执行但node提示找不到。可能是npm和node安装路径分离的情况最常见的来源是Windows下某个项目自动安装的独立npm。确认的方式是执行where node和where npm看两个命令在不在同一个目录。不在的话修复方法多半是卸载多余的npm重新用统一方式安装。场景三macOS用户执行nvm提示找不到。nvm本身不是命令而是一个shell函数它定义在用户的shell配置文件中。确认 ~/.bashrc、~/.zshrc或~/.profile里是否已正确加载nvm的初始化脚本修改配置后执行source ~/.zshrc让配置生效。5.3 依赖安装相关报错场景一npm install报错EACCES permission denied。这是权限问题常见于用root用户安装了软件后又切回普通用户或者全局安装目录权限设置不当。解决方法是不要在系统全局目录直接安装依赖对社区常见的chmod处理方式我不推荐最稳妥是重新配置npm全局安装路径或者使用nvm这类版本管理器——用nvm安装的Node.js属于当前用户完全绕开全局权限问题。场景二安装一个包时提示ERESOLVE unable to resolve dependency tree。这是npm在解析依赖冲突时终止了安装。一般不应当盲目加--force或--legacy-peer-deps跳过先看报错信息里提到的冲突包名手动调整该包的版本或者确认一下是否真的要同时使用两个互相冲突的库版本。推荐先单独安装其中一个库npm install 包名 --legacy-peer-deps只是兜底方案并不是长久之计。场景三安装过程极慢或者直接超时。网络所限上文中配置镜像源是第一选择。改完后注意部分公司内部私有仓库需要独立配置源地址不同源间的切换用npm config set registry就能完成配合--registry参数可以在单条命令中临时指定源不改变全局配置npm install --registry https://registry.npmmirror.com场景四本地明明装了某个包但运行时直接报Cannot find module 包名。可能是包没有安装到当前项目的node_modules里或者包被安装到了全局而项目内找不到。处理思路是进入项目根目录执行npm list 包名确认依赖情况然后执行npm install 包名把依赖装进当前项目。6. 开发工作流实操记录一个真实项目的完整流程前面把命令拆开讲了但很多新手真正困惑的是“这些命令怎么连起来用”。下面我以一个模拟项目X的开发为背景把从零开始、到多人协作、再到发布的完整流程走一遍这个流程有很强的可复制性。项目起点某跨平台系统开发任务两个人协作主要需求是实现一个用户登录模块使用Express框架编写后端服务使用Git做版本管理。模块目录名定为user-login。流程第一步初始化本地仓库并创建基础文件cd user-login git init npm init -y第二步安装Express并生成入口代码npm install express touch index.jsindex.js写入一个最简单的服务const express require(express); const app express(); app.get(/, (req, res) res.send(User login service running)); app.listen(3000, () console.log(Server listening on port 3000));第三步第一次完整提交。这是整个流程中最应该养成习惯的动作代码不要堆到最后一次性提交一次提交对应一个逻辑功能后续用git log排查问题时才方便定位git add index.js package.json package-lock.json git commit -m 初始化项目并实现用户登录服务基础框架注意这一步我没有执行git add .把所有文件都加进去而是明确列出这次提交应包含的文件。有时候目录里会有一些不想提交的临时文件明确指定比无脑全都加更安全。第四步开发一个新功能用户注册接口。在index.js增加一个路由后执行git diff查看这次改动和之前的差异确认无误后再次提交git diff git add index.js git commit -m 新增用户注册路由第五步创建远程仓库并推送。在代码托管平台创建空仓库后把本地仓库和远程关联git remote add origin https://github.com/某组织/user-login.git git push -u origin main-u参数指定本次推送的分支为上游分支之后就可以直接执行git push和git pull不用每次写分支名。第六步模拟团队协作场景。假设同事A克隆了该仓库新建了一个功能分支做开发git clone https://github.com/某组织/user-login.git git switch -c feature-register开发完成后合并回主分支再推送git switch main git merge feature-register git push如果合并时出现冲突按3.4里的方法手动解决。这套流程建分支、开发、合回主分支、推送是绝大多数团队使用Git的标准模式熟练之后能适应各种协作方式。关于团队协作还有一个原则想特别强调不要直接在main分支上开发功能。哪怕是个人项目养成“开发分支做完再合回”的习惯能有效避免项目历史混乱。在实际的项目中主线分支通常是被保护的直接push会被拒绝必须通过合并请求的方式完成合并。7. 实操心得与一段时间的自省写到这里把最后几句经验留给你。这些东西不是文档里的标准答案是我自己踩坑后总结的。第一Git命令不需要死记硬背但git status和git log这两个命令必须形成肌肉记忆。不确定当前仓库什么状态时先跑git status不确定历史怎么发展的先跑git log --oneline --graph。所谓“不知道下一步用什么命令”排查的起点基本都是这两条。第二提交信息要当作正式的沟通文档来写。跟队友合作时一行清晰准确的提交说明能让代码审查的人少问十个问题。推荐的提交信息格式包括三部分做了什么动词开头为什么这么做影响了什么范围。例如“重构用户验证逻辑统一错误处理减少重复代码”就比“update stuff”有价值得多。第三Node.js版本管理有条件就用nvm。别嫌多此一举等到某个老项目因为Node版本太新而装不上依赖或者新项目因为Node版本太旧而报语法错误时你会明白一个能随手切换版本的工具有多省心。第四npm安装依赖之前先看看项目里是否有package-lock.json。有就在clone后直接npm ci这个命令严格按照lock文件安装依赖比npm install更快更干净也避免了lock文件被悄悄改动。我的习惯是CI环境和本地首次clone时用npm ci日常开发追加依赖时用npm install。第五配置镜像源这件事一旦换了环境要重新设置。接新电脑、换公司网络时第一件事不是写业务代码而是检查node版本、npm源和Git全局配置这三样确认好后面能省下大量碎片时间。我把这三步合称“新环境三件套”每次都按这个顺序过一遍基本不会再被环境问题卡住。Git和Node.js的学习曲线不算陡但也不像表面看起来那么平缓。真正见效的方式只有一个在真实项目里反复用用得多了就会自然记住那些命令和原理。这篇内容覆盖了绝大多数日常场景照着走完一个完整流程你就已经超过了相当一部分“会clone但不会处理冲突”的开发者。
