项目常用指令说大不大说小不小。很多团队一开始觉得这种东西随手一查就有没必要单独整理可真到了交付节点总有人卡在一条命令上分支推不上去、依赖装不下来、容器起不来、日志翻不到。我这些年带项目、做交付最深的体会是与其让每个人靠记忆和搜索引擎拼凑命令不如在项目一开始就沉淀一份“项目常用指令清单”让所有人都站在同一套操作语言上。这篇内容就围绕项目里最实用的指令展开从协作、构建、测试到部署上线把我在真实项目里反复用到的命令和排查思路一次说清楚。这份清单适合谁适合刚接手项目的开发同学、需要自己跑通全流程的全栈新人也适合要带团队统一操作规范的技术负责人。它不追求把每个工具的所有参数都列出来只解决一个核心问题项目从拉代码到上线的全链路里哪些指令是天天要用的怎么用才不出错。1. 先搭一张“项目指令地图”分类原则与团队落地方法很多人以为整理常用指令就是把用过的命令抄一遍其实不是。没有分类的命令清单本质还是散装笔记关键时刻根本想不起来去查。我在项目里习惯先把指令分成几个固定板块代码协作、依赖管理、构建测试、部署运维、日志排查。每个板块对应项目生命周期的不同阶段查起来路径最短。1.1 为什么指令要分类而不是罗列举个例子新人入职第三天要跑前端项目。如果清单只写了一堆npm install、npm run dev、git pull他会觉得都会。但遇到依赖装不上或者本地端口被占用他就不知道去哪找答案。而如果清单里明确写着“构建测试板块 —— 依赖异常处理”他至少知道问题归属哪个环节再配合里面的排查命令效率完全是两回事。分类还有一层好处方便维护。项目迭代过程中指令一定会变依赖包管理器可能从 npm 换到 pnpm部署方式可能从裸机变成容器。分类清晰后更新某个板块不影响其他内容团队协作维护时也不会互相覆盖。1.2 一份可落地的指令清单长什么样我推荐用项目仓库里的docs/commands.md来维护这份清单跟着代码库一起走而不是放在某个人的云笔记里。这样每次更新都有提交记录谁改了什么一目了然。清单结构我一般这样组织环境信息记录 Node 版本、包管理器版本、Java 版本、构建工具版本等基线避免出现“我本地能跑”的问题。日常指令按进入项目、拉取代码、安装依赖、启动服务的顺序排列保证新同学按顺序敲就能把项目跑起来。异常处理单独列一块只放高频问题对应的命令片段比如清理缓存、查看端口、重启服务。部署相关上线、回滚、查看日志的操作命令这块我会要求写清楚每一步的前提条件和预期结果。1.3 如何让团队成员主动用这份清单命令清单最怕写完之后没人看。我这边有几个实用做法。第一把清单入口写到项目的 README 开头而不是藏在 docs 目录深处第二Code Review 时如果看到有人用了清单外的命令变体顺手问一句“要不要补进文档”让清单跟着真实操作走第三定一条规矩谁踩了坑并找到解决办法谁就负责把对应命令更新进文档。几次迭代之后这份清单就会变成团队真正依赖的操作手册。2. 日常协作最高频的 Git 指令实操拆解代码协作是项目的生命线Git 指令也是“项目常用指令”里占比最大的部分。这里不讲那些一辈子用不上一次的偏门参数只拆解团队协作中真正高频的指令以及每个指令背后容易踩的坑。2.1 拉取与提交的基础姿势git pull和git push是每天都要用的但很多人忽略了一个细节git pull默认执行的是 merge 合并方式如果本地有未提交的修改或者远程分支有人已经提交了新代码就可能产生合并冲突甚至直接弹出一个 Vim 编辑器让你写提交信息。我个人的习惯是拉代码之前先看一眼状态把本地改动梳理清楚再动手。比较稳妥的日常操作序列是这样的# 先看清当前状态 git status # 拉取远程更新推荐用 rebase 方式保持历史线性 git pull --rebase # 如果本地有未提交改动先临时保存 git stash # 拉取完成后恢复本地改动 git stash popgit pull --rebase这个指令值得多说一句。它把你的本地提交先放到一边拉取远程最新的提交再把你的提交重新应用到最新代码之上好处是提交历史是一条直线review 起来更清爽。团队不大、协作不复杂的情况下这个操作比默认的 merge 体验好很多。2.2 分支管理与合并冲突处理项目常用指令里分支操作是避不开的。我的基本流程是需求开始前从主干拉新分支命名用feature/模块名-简述开发完回主干合并。这里最常用的几条指令# 从主干拉取最新代码 git checkout main git pull # 创建并切换新分支 git checkout -b feature/user-login # 开发完成后切回主干拉最新代码 git checkout main git pull # 将 feature 分支合并进主干 git merge feature/user-login冲突是合并时最容易让人头疼的事。我的经验是不要慌着用git abort或者手动乱改。正确顺序是先git status找到冲突文件打开文件搜索、、标记逐个判断保留哪边的代码。如果冲突涉及多方改动最靠谱的办法是拉当事人一起对一下避免把别人的逻辑改没。解决完冲突后重新执行git add和git commit即可。记住git merge过程中产生的冲突解决后永远不要带--force或--hard之类的参数那会把提交历史弄得更乱。2.3 三个容易被忽视的高频指令git stash、git cherry-pick、git tag这三条指令在日常项目里使用频率不低但很多清单不会专门写。git stash的场景是你正在开发新功能线上突然报了个紧急 Bug需要立刻切换分支修复。本地改动不想提交也不想丢失这时执行git stash把改动暂存起来切到其他分支修复再切回来执行git stash pop恢复。注意 stash 的栈是后进先出多个 stash 时用git stash list查看git stash apply stash{1}指定恢复某一个不要一直无脑 pop。git cherry-pick适合把一个分支上特定的提交复制到另一个分支。比如修复线上问题时在主干上改了一个提交发现这个修复 feature 分支也需要直接git cherry-pick commit-id就能把这个提交复制过来而不必把整个主干合并进 feature 分支。这个指令在分支并行协作的项目里几乎是救命的。git tag则是给版本打标记。我习惯在每一次可发布的节点打上 tag格式类似v1.2.0。发布后用git tag查看所有版本用git checkout v1.2.0切到指定版本排查问题时非常好用。它能精确告诉你线上跑的是哪一行代码这在排查“为什么本地正常线上异常”时是首要确认步骤。2.4 提交规范与回滚纪律项目里最常见的回滚指令是git reset和git revert两者容易混淆。简单说git reset是把本地提交记录往回拨适合还在自己分支、还没推送的情况下使用git revert是生成一个新的反向提交把之前某个提交的改动撤销掉提交历史仍然向前走适合已经推送、其他人也已经拉取的提交。# 本地撤回最近两次提交但保留改动内容 git reset --soft HEAD~2 # 本地彻底撤回最近一次提交且删除改动内容 git reset --hard HEAD~1 # 撤销一个已经推到远程的提交生成反向提交 git revert commit-id我踩过的坑是分支推到远程之后尽量不要用git reset --hard配合git push --force去改历史。如果只有你一个人用这个分支还好多人共用时强制推送会让所有人的本地状态和远程不一致轻则互相覆盖重则丢失提交。团队协作的稳妥做法是用git revert。3. 构建测试阶段的项目常用指令集项目跑起来之后构建和测试指令是每天高频出现的。前端看包管理器后端看语言构建工具但核心思想一致安装依赖、跑通测试、构建产物一步都不能少。3.1 npm / pnpm 系列指令的使用习惯前端项目里npm install是最常见的指令。但这里有几个细节值得强调。第一npm install和npm ci不一样。npm ci会严格按照 lock 文件安装删除 node_modules 后全新安装速度更快且版本更一致适合 CI 环境使用。本地开发想保持环境干净时也可以用npm ci。第二npm install安装依赖时尽量不要随手加--force或者--legacy-peer-deps先用提示信息判断是版本冲突还是 registry 问题很多依赖装上之后跑不起来都是因为用了强制安装而忽略了 peer 依赖不匹配。如果项目已经切换到 pnpm常用指令变成了pnpm install、pnpm dev、pnpm build。pnpm 的优势在于依赖存储在全局仓库里磁盘占用小、安装速度快。不过要注意pnpm 对 peer dependency 的检查比 npm 严格遇到权限问题或者幽灵依赖问题先去 pnpm 的文档里找处理方式不要直接猜。3.2 Maven / Gradle 的常见操作Java 项目里Maven 和 Gradle 是最主流的构建工具。Maven 的常用指令是mvn clean package -DskipTests这个指令会清空 target 目录并重新构建跳过测试跑更快。如果只想打包不跑测试-DskipTests足够。真正需要跳过编译阶段的测试执行时用-Dmaven.test.skiptrue。两者差别在于前者编译测试代码但不执行后者连测试代码都不编译。我一般喜欢用-DskipTests至少保证测试代码本身的语法没有编译问题。Gradle 项目则是./gradlew clean build或者./gradlew bootRun。gradlew比系统全局的gradle指令更靠谱它会自动下载项目指定版本的 Gradle避免本地环境版本不一致导致构建行为不同。项目里我强制要求统一用./gradlew禁止直接用全局 gradle 命令这是减少“我本地能跑”问题的重要措施。3.3 测试指令与 CI 脚本里的常用命令常见的前端测试指令是npm run test但这行命令在不同项目里含义差很多。有的是单次运行有的是 watch 模式持续监听。如果 CI 里跑的是 watch 模式整个流水线会一直挂着直到超时。所以我建议在项目脚本里明确区分test单次运行和test:watch监听模式并在 CI 配置中使用固定参数。例如 jest 项目单次运行可以写成npm run test -- --silent --ci--silent减少无用输出--ci让 jest 按 CI 环境运行不会进入 watch 模式。类似的Java 项目的测试在 Maven 里可以这样控制mvn test -DtestUserServiceTest只跑某一个测试类这种精准执行在排查问题时能省大量时间。CI 里的原则只有一个命令必须在非交互、无监听的环境下可以稳定执行完任何需要人工输入或者等待的指令都要规避。4. 部署上线环节的高频指令与注意事项项目走到部署上线指令就不仅是开发环境那套了。远程登录、进程管理、日志查看、容器编排每一步都有对应的命令。这一节我按实际部署流程来写。4.1 远程服务器操作指令部署的前提是能安全地访问服务器。ssh指令是基础但很多人只用了其中最浅的用法。建议在本地配置好 SSH 密钥然后用别名登录避免每次输账号密码# 在本地 ~/.ssh/config 中配置服务器别名 # Host my-server # HostName 192.168.1.10 # User deploy # IdentityFile ~/.ssh/id_ed25519 ssh my-server文件传输是部署时绕不开的事。scp适合偶尔传单个文件rsync适合同步整个目录并且支持增量传输。项目里有静态资源需要更新时我一般用 rsyncrsync -avz --delete dist/ deploymy-server:/var/www/project/这条命令里的-avz表示归档模式并压缩传输--delete表示目标端多出来的文件自动删除保证目录和本地完全一致。注意第一次执行rsync时不要在目标目录不熟悉的情况下加--delete极有可能把服务器上其他没打算删的文件干掉。稳妥做法是先不加--delete同步一遍确认目录结构正常后再按需启用。4.2 进程管理与日志查看指令服务跑在服务器上通常用 systemd 或者进程管理工具来控制。如果你是 Java 应用可能用systemctl系列命令sudo systemctl status project sudo systemctl restart project sudo journalctl -u project -fjournalctl -u project -f是查看服务日志并实时刷新的常用方式排查启动失败时先用这条命令看最近几十行错误日志基本能定位大多数问题。如果是 Node.js 应用很多人习惯用 PM2 做进程管理。常用的指令包括pm2 list pm2 logs project pm2 restart project pm2 start app.js --name projectpm2 的优势是进程崩溃后会自动拉起还能查看内存和 CPU 占用。但有一点要特别注意不要把应用日志和业务日志混在一起。最好让应用按文件输出完整日志pm2 logs 只作为进程级输出查看这样排查问题时信息更清晰。4.3 容器环境里的常用指令现在很多项目已经容器化Docker 本身也是“项目常用指令”里的大户。开发环境下最常用的是docker compose系列docker compose up -d docker compose down docker compose ps docker compose logs -fdocker compose up -d是启动全部服务并后台运行-d必须带上否则终端会被日志刷屏。docker compose down会停止并移除容器但要注意加不加-v参数差别很大加-v会把卷数据一并删除如果项目里有用 docker volume 存的数据直接 down 再 up数据还在执行docker compose down -v之后数据就真没了。这个参数我建议非必要不加。排查容器问题时先docker compose ps看状态再看docker compose logs -f 服务名看输出。如果容器一直重启大概率是启动命令报错或者健康检查失败核心思路永远是先看日志再改配置。4.4 回滚操作如何做得又快又稳上线出问题并不可怕可怕的是没有快速回滚的手段。在裸机部署的项目里我会保留上一个版本的目录或压缩包。发布新版本时把当前版本包保留备份出问题时执行快速切换# 假如项目目录是 /var/www/project版本目录 /var/www/releases sudo ln -sfn /var/www/releases/project-v1.2.1 /var/www/project利用软链接切换版本一条命令完成回滚整个操作过程在几秒内结束。容器环境下更简单用镜像 tag 来管理版本回滚时直接指定上一个镜像 tag然后重新启动docker compose up -d --no-deps project这里--no-deps表示只重新创建指定服务不连带重启依赖服务速度更快影响面也更小。回滚之外还有一条纪律回滚之后一定要保留现场拿到错误日志和版本号而不是回滚完就当无事发生。没有追溯的上线事故后面大概率还会再犯。5. 常见问题与排查技巧速查表这一节我把项目日常运行里出现频率最高的几类问题整理成速查表每条都附上最直接的排查指令和思路。工作多年我发现项目运维里 80% 的故障其实都集中在几个固定场景。5.1 指令敲了却没反应的排查方向最常见的虚假故障是“敲了命令什么都没发生”。这种情况通常不是指令错了而是终端环境的问题。首先用pwd确认自己所在的目录是不是项目根目录很多指令在错误目录下执行时后果就是找不到文件或者命中了一个完全无关的同名命令。其次确认当前使用的终端环境是否和项目脚本匹配举例来说在 Windows 的 CMD 里跑 shell 语法会直接报错排查起来很迷惑。如果确认环境无误下一步就是查看命令的详细输出。很多命令的报错信息隐藏在日志文件里或者需要添加参数来开启。比如 Maven 构建时可以加-X开启调试日志npm 安装时可以加--verbose查看详细进度。这些参数虽然平时不用排查问题时是排头兵。5.2 端口占用、连接超时这类高发问题怎么处理端口占用在本地开发里出现频率极高前端 dev server 默认跑在 8080、3000后端服务常用 8080/9090冲突是家常便饭。不要直接重启电脑先准确找到占用进程# 在 Linux/Mac 上查看 8080 端口被哪个进程占用 lsof -i :8080 # 在 Windows 上使用 netstat 查找 netstat -ano | findstr 8080拿到进程号后确认是自己项目的旧进程再加kill -9 pid。这里提醒一句kill 之前看一下进程是什么别把数据库或者中间件进程误杀了。我见过有人把本地 MySQL 杀掉还以为是端口被占用解决了。连接超时问题通常是网络或者远端服务问题。先测连通性ping看网络通不通再用telnet host port或者nc -zv host port测指定端口是否开放。不推荐的排查方式是盲目重试因为如果是服务端没有启动重试再多次也没有意义。先确认端口状态再往上层排查。5.3 从日志里快速定位问题日志是项目事故排查的上帝视角但不会看日志的人只能盯着屏幕干着急。我的习惯是先搜关键词不要试图从头到尾读日志。查询日志文件的常用指令# 查看末尾 200 行 tail -n 200 app.log # 在日志里搜索某个异常关键词 grep -n ERROR\|Exception app.log # 跟踪日志文件实时输出 tail -f app.log如果日志量太大先按时间范围过滤。例如只有上午 10 点 15 分左右出了问题可以用 grep 配合时间戳来缩小范围。专门的日志平台里搜索语法类似但核心思路一致先确定报错类型和时间点再沿堆栈信息向上找触发链路。切记不要一上来就全文搜索堆栈里的类名那个太长了搜索业务方法名或请求路径更高效。6. 高频指令勘误与使用心得常用指令清单看着简单真正用起来还是有不少会误导新人的细节。这一节我把一些容易出错的命令细节和替换方案写清楚希望帮你少走弯路。6.1 容易混淆的指令对比npm run build和build -x之类的记忆碎片是最容易混淆的。我整理过一张对照表放在清单里帮助新人快速分辨易混淆指令正确理解常见误区git pull从远程拉取并合并不弹窗才是正常实际有时会弹提交编辑器git reset --hard本地提交记录回退并清除改动已推送的分支千万别用会覆盖队友代码npm install按 package.json 安装依赖不读 lock 文件可能装出不同版本npm ci严格按 lock 文件安装会删除 node_modules启动前不建议反复执行docker compose down停止并移除容器加-v会删除数据卷非必要不加6.2 给项目清单做减法最后分享一个建议项目常用指令不是越多越好而是越少越好。一份用不上的指令没人会看而每人每天都要用的指令一定要放在最显眼的位置。我每次新增指令都会问自己一个问题这条指令如果一个月内用不到两次就不该出现在常用清单里应该挪到更深层的文档里。根据我个人经验项目里最值得反复打磨的就是这份“常用指令清单”。它不是写给别人看的静态文档而是跟着团队踩坑节奏一起生长的操作沉淀。每次事故复盘第一件事不是写长篇报告而是更新指令清单把排查路径里用到的命令和顺序补充进去。半年下来团队出问题的概率明显下降新人也更容易融入项目。如果你所在的项目还没有这样一份清单我的建议是今天就建起来先简洁后完善跑通第一次之后自然会越滚越全。