鲸游很多人在Cursor里把本地项目写好了，最后卡在“上传到GitHub”这一步。我上周连续帮三个朋友处理了同一个问题，他们的操作几乎一样：代码没问题，就是不知道在Cursor里怎么把项目推到GitHub上。这套流程并不只属于Cursor，任何编辑器、任何终端都能用，只是Cursor把步骤分得清楚，容错也高一些。我尽量把里面的每一步为什么这样做也讲明白，后面你换到任何工具都不会发怵。
1. 为什么我建议用Cursor完成仓库上传这件事
1.1 一个奇怪的卡点：代码没问题，提交不会做
很多人写代码是跟着教程一步步来的，但对“把项目上传到GitHub”这件事没有形成完整概念。常见的方式有三种，都挺费劲。
第一种，在GitHub网页上手动点“Add file”，再一个个粘贴代码。文件少还能忍，文件一多，尤其在本地已经有几十个文件的项目里，纯手工上传基本是灾难。
第二种，下载了Git，但只在网上抄了一串命令，不知道每一条命令在干什么。一旦报错，整个人就卡住。
第三种，怕传错东西。项目里可能有node_modules、.env、dist目录，把这类东西传上去轻则仓库臃肿，重则泄露密钥，所以宁可一直不传。
我自己最开始也是第二种，命令全背下来了，可一旦遇到“rejected”“denied”这种字眼就慌。后来我开始在Cursor里直接操作，发现它的价值不只是写代码，而是把终端、编辑器、AI解释器放在一个窗口里，报错之后可以马上把错误信息扔给AI，让它帮忙看问题出在哪。这份从容是以前在纯命令行里没有的。
1.2 为什么是Cursor，而不是其他工具
选Cursor有几个实际原因。
第一，Cursor内置终端。按一个快捷键就能打开，不需要额外开一个终端窗口，也不用在项目目录和终端之间来回切换。
第二，Cursor的AI可以根据上下文解释报错。你push失败，把报错原文发给它，它能结合当前项目结构给出相对靠谱的修复建议。
第三，也是很多教程没提到的：Cursor本身不会把你锁死。它底层用的还是Git那一套，所以你在Cursor里学会的命令，在VS Code、IDEA，甚至纯命令行里一样能执行。这就是标题里“其他也能用”的意思：你学的不是“Cursor怎么上传”，而是“Git怎么工作”。
所以这篇文章不会教你什么花哨的按钮，而是把完整的命令链路走一遍。这样就算哪天你换了编辑器，依然能完成同样的事。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 开工前的三件套：Git、Cursor、GitHub账号
刚开始做这件事，最容易漏掉的是环境准备。有些人把命令输入到终端，发现“git不是内部或外部命令”，然后就开始怀疑人生。其实只要把三个前提确认好，后面的过程就很顺。
2.1 安装Git并确认版本
Git是上传的核心工具。打开终端，输入：
bash复制git --version
如果有类似git version 2.40.0的输出，说明Git已经装好。如果提示找不到命令，那就需要安装：
- Windows：到Git官网（git-scm.com）下载安装包，一路下一步。安装时建议选择默认选项，安装完成后重新打开Cursor，让环境变量生效。
- macOS：装了Homebrew的话可以直接用
brew install git，没装的话可以从Git官网下载pkg安装包。 - Linux：Debian/Ubuntu用
sudo apt install git，CentOS/RHEL用sudo yum install git。
安装完成后，重新打开终端，再执行一次git --version确认。一般情况下，新装完Git后要重启编辑器，终端才能读到新环境变量，这个细节很多人忽略。
2.2 检查Cursor侧需要确认什么
Cursor本身不需要额外安装Git插件，它自带的“源代码管理”面板和终端都能直接调用系统里的Git命令。
打开Cursor后，你只需要确认两件事。
第一，你打开的是一个项目文件夹，而不是单个文件，这样Git才能识别整个项目的结构。第二，终端能正常执行命令。按Ctrl+``（macOS上是Control+``）唤起内置终端，输入pwd看看当前路径是不是项目根目录。如果不在，用cd切换进去。
建议整个流程都在项目根目录完成，避免后面git add .把无关文件加进来。
2.3 在GitHub上建好空仓库
接下来去GitHub网站，登录账号，点右上角的“+”号，选择“New repository”。这里有几个需要认真想的地方。
仓库名称：一般和项目文件夹同名就行，全英文小写加短横线，不要带空格。
描述：可写可不写，但写上别人一眼就能看懂项目是干嘛的。
可见性：public是公开的，任何人都能看到；private是私有的，只有你或你授权的人能看到。个人学习项目如果不打算给别人看，用private就行，后面想改成public随时可以改。
| 属性 | public | private |
|---|---|---|
| 谁可以看到 | 所有人 | 只有你和被授权的人 |
| 适合场景 | 开源项目、作品集 | 私人项目、商业项目 |
| 能否修改 | 可以随时改为private | 可以随时改为public |
最重要的一点：不要在网页端勾选“Add a README file”“Add .gitignore”“Choose a license”。很多新手会顺手勾上，结果本地已经有代码，远程又自动生成了README，后面推送时就会遇到远程仓库和本地仓库历史不相关的冲突。我见过太多人卡在这一步。创建空白仓库就好，其他内容全部留空。
创建完成后，页面会显示一个HTTPS地址，类似：
text复制https://github.com/你的用户名/仓库名.git
这个地址记下来，下一步要用。如果你之前配置过SSH key，也可以选SSH形式，但对新手来说，HTTPS最简单，后面配合Personal Access Token登录即可。
3. 在Cursor里把项目推上GitHub的完整操作链路
准备工作做完，开始正式操作。这一节我按顺序列出每条命令，并解释每一步为什么这样做。建议你打开Cursor终端，边看边操作。
3.1 用Cursor打开项目并唤起终端
在Cursor的欢迎界面选择“Open Folder”，找到你的本地项目文件夹。打开后，按Ctrl+``切换到内置终端。要注意，终端当前的路径必须和项目根目录一致，否则后面的git init`会在错误的地方初始化。
如果路径不对，用：
bash复制cd 你的项目路径
切换到项目目录。
3.2 初始化仓库：git init
第一次把项目目录变成Git仓库，需要执行：
bash复制git init
执行后终端会显示类似Initialized empty Git repository in ...。这句话的意思是，Git已经在这个文件夹里建了一个隐藏的.git目录，专门用来记录版本、提交历史、分支信息等。这个目录在文件管理器里通常看不到，但它是Git仓库的“大脑”。
这里解释一下：不要把.git目录手动删除，它和项目代码一样重要。你以后的所有提交记录、分支结构都在这一个目录里。
3.3 把文件加入暂存区：git add
初始化完成后，先看一下当前仓库的状态：
bash复制git status
你会看到一堆“Untracked files”，意思是这些文件还没有被Git跟踪。要把它们加入暂存区，执行：
bash复制git add .
这个命令会把当前目录下所有未跟踪文件加入暂存区。这里有个很重要的提醒：git add .会把所有文件都加进去，包括node_modules、dist、.env这些你不想上传的目录。所以在执行之前，最好先建一个.gitignore文件，把不需要上传的路径写进去。
.gitignore文件的写法很简单，一行一个规则，比如：
gitignore复制node_modules/
dist/
.env
.DS_Store
其中node_modules/表示忽略这个目录以及目录下的所有内容。这个文件本身应该被提交，所以它不要写在忽略规则里。
如果项目里已经有了.gitignore，那直接执行git add .就行。如果没有，先创建文件，再执行。
使用git add .之后，再执行git status，你会看到文件列表变成了绿色，说明它们已经进入暂存区。这一步相当于告诉Git：“这些文件我准备提交了，先放在待提交区。”
3.4 提交到本地仓库：git commit
暂存区只是临时存放，真正的“提交”动作由commit完成：
bash复制git commit -m "first commit"
双引号里是提交信息，建议写清楚这次提交做了什么。比如“init project”或“首次提交”。提交信息是为了以后翻历史时能快速知道每次改动是什么，不要用“111”“aaa”这种无意义内容。
如果这一步出现类似下面的报错：
text复制Please tell me who you are.
这说明Git不知道你是谁，需要先配置身份信息：
bash复制git config --global user.name "你的名字"
git config --global user.email "你的邮箱"
这里的邮箱建议和GitHub账号邮箱一致，提交记录才能正确关联到你的GitHub账号。配置完再执行git commit -m "first commit"，正常情况下会显示1 file changed, ...之类的信息，说明提交成功。
3.5 关联远程仓库：git remote add
commit只是把改动记录在了本地Git仓库，还没和GitHub发生任何关系。要让两者产生联系，需要把本地仓库和远程仓库关联起来：
bash复制git remote add origin https://github.com/你的用户名/仓库名.git
这里origin是远程仓库的默认别名。你可以把它理解成给远程地址起了一个短名字，后面推送时写origin就不用重复输入整个URL。一个本地仓库可以关联多个远程地址，名字可以不同，但习惯上第一个都叫origin。
如果输错了，可以用git remote -v查看当前关联的地址，用git remote remove origin删除旧地址，然后重新添加。
3.6 统一分支名并推送：git push
GitHub新版默认分支名是main，但有些本地的Git版本默认分支名还是master。分支名不一致会导致推送被拒绝，所以先统一：
bash复制git branch -M main
-M的意思是强制重命名当前分支为main，即使原来有分支也直接覆盖。
然后推送：
bash复制git push -u origin main
第一次推送时，终端会弹出GitHub的登录窗口，或者提示输入账号信息。这里有一个让很多人困惑的点：如果你用的是HTTPS地址，GitHub已经不再支持用账号密码直接登录，需要填写用户名和Personal Access Token，密码栏填的是Token而不是账号密码。
Token的生成方式：GitHub头像 -> Settings -> Developer settings -> Personal access tokens -> Tokens (classic) -> Generate new token。生成时勾选repo权限，复制生成的token。这个token只显示一次，务必保存好，也不要提交到仓库里。为了安全，可以给token设置有效期，比如90天，过期后再重新生成。
推送成功后，终端会显示类似Branch 'main' set up to track remote branch 'main'的信息。这时刷新GitHub仓库页面，就能看到你的代码了。
3.7 后续更新的常规循环
项目之后每次有改动，不再需要重复git init和git remote add，只需要三步：
bash复制git add .
git commit -m "描述这次改动"
git push origin main
这个循环就是日常开发里最常见的提交节奏。第一次推送时用了-u参数，后面推送直接写git push也可以，因为本地分支已经和远程分支建立了跟踪关系。
4. 不想敲命令？Cursor里的图形化路径和它们的边界
命令行的优点是一步到位，但对一些人来说，看到黑框框就紧张。Cursor本身提供了图形化操作入口，而且体验相当成熟。如果你实在不想碰命令，可以先走这条路。
4.1 内置的源代码管理面板
在Cursor左侧边栏有一个“源代码管理”图标，点开后能看到所有改动文件。
操作逻辑很直观：
- 文件列表右侧的“+”号，对应
git add，把文件加入暂存区。 - 顶部的输入框里写提交信息，点击“提交”，对应
git commit。 - 点击“同步更改”或“推送”按钮，对应
git push。
如果在面板中没有看到“推送”按钮，可以先点提交按钮，提交完成后面板上方会出现“同步更改”的提示，点击后就能把本地提交推送到远程。
这个面板本质上是在调用Git命令，所以它和命令行是完全等价的。面板适合看“谁改了什么”这类问题，命令行适合执行精确操作，两者各有优势。
4.2 扩展：GitLens和Git Graph
如果你想要更丰富的可视化，可以在扩展市场安装GitLens和Git Graph。
GitLens能显示每一行代码最后是谁改的、在哪个提交里改的，定位历史问题非常好用。Git Graph能把分支和提交历史画成图表，适合理解整个项目的时间线。安装方式是在Cursor扩展面板搜索名字，点安装即可。
这俩主要用于查看历史，真正执行提交推送，还是用自带面板或者命令。
4.3 GUI方式的边界
图形化面板有一个不足：报错被包装成“操作失败”之类的提示，看不到底层命令的完整输出。一旦遇到身份验证、分支冲突这类问题，面板里能获取的信息很有限，反而让人不知道下一步该干吗。
我的建议是：日常提交用图形化面板没问题，但出问题时要回到终端执行git status和git push，把原始报错信息看明白。这也是为什么我在这篇文章里花了大量篇幅讲命令，因为你迟早要面对终端。
5. 我在实际推送中踩过的几个坑：从报错到解决
这一节不是理论，是我实测过程中真实出现的报错和排查链路。每个坑都按“现象 -> 排查 -> 解决”的顺序写，你遇到类似问题时可以照着走一遍。
5.1 提交时报错“Please tell me who you are”
现象：执行git commit时，终端直接拒绝。
排查：Git的提交记录需要有作者信息，没有配置时会直接报错。可以先执行git config user.name和git config user.email，如果输出为空，说明确实没配。
解决：
bash复制git config --global user.name "你的名字"
git config --global user.email "你的邮箱"
配置完重新git commit就正常了。这里我遇到过一个细节：如果用户主目录下之前的Git配置写错了邮箱，后面GitHub上的提交记录不会指向你的账号。检查方式是用git config --list查看当前所有配置，重点看user.email是不是你常用的GitHub邮箱。
5.2 推送被拒绝：本地分支和远程分支不一致
现象：执行git push -u origin main时，提示“rejected”或“failed to push some refs”。
排查：先看本地分支名。执行git branch，如果显示* master，而远程仓库默认分支是main，推送自然对不上。
解决：统一分支名：
bash复制git branch -M main
再重新推送。这个坑非常常见，因为旧版Git初始化时默认分支叫master，新版Git和GitHub默认用main。两者默认分支名不一致是历史遗留问题，具体原因这里不展开，你只需要知道本地分支名和远程分支名必须一致。
还有一种相关情况是，你在创建GitHub仓库时勾选了“Add a README”，导致远程仓库有了一条历史，而本地仓库是全新历史，推送时也会被拒绝。这种情况下的处理方式不太建议新手直接用git push -f强制覆盖，因为你可能把远程已有的内容丢掉。更稳妥的办法是用git pull origin main --allow-unrelated-histories把远程内容拉下来合并，不过最根本的解法还是创建仓库时不要勾任何初始化文件。
5.3 把node_modules整个推上去了
现象：推送速度极慢，GitHub仓库里出现了成千上万个文件。
排查：执行git status，看到node_modules/在待提交列表里。
解决：创建.gitignore，加入node_modules/，然后：
bash复制git rm -r --cached node_modules
git add .
git commit -m "remove node_modules from git"
git push origin main
说明一下git rm -r --cached node_modules的作用：它会把node_modules从Git的跟踪状态里移除，但不会删除你本地文件。这一步是必要的，因为如果你之前已经提交过一次，即使现在加了.gitignore，Git还在继续跟踪。--cached的意思是只从索引里移除，不动工作区文件。
依赖目录不该进仓库的原因很简单：一个几百MB的node_modules会让仓库体积爆炸，团队其他人拉取代码时也很痛苦。正确的做法是提交package.json和package-lock.json，其他人拉代码后执行npm install就能恢复。
5.4 推送时提示“Support for password authentication was removed”
现象：输入GitHub密码后，终端直接报错。
排查：GitHub从2021年起就不支持用账号密码进行HTTPS推送了，必须用Personal Access Token或者SSH key。
解决：去GitHub生成token，勾选repo权限，然后在终端提示输入密码时粘贴token。如果你用的是图形化登录窗口，选择“Sign in with your browser”也可以，浏览器完成授权后终端会自动继续。
Token很容易被误以为和密码是同一个东西，这是新手最常见的问题。你把Token当成密码填进去，本质上是一个有期限的访问凭证，泄露了随时可以在GitHub后台撤销。
5.5 大文件推送失败：remote ended unexpectedly
现象：推送大文件或很多文件时，终端提示“The remote end hung up unexpectedly”。
排查：Git通过HTTP推送时，单次请求的数据量有上限，超了就会断开。
解决：临时调大缓冲：
bash复制git config http.postBuffer 524288000
这个命令把HTTP缓冲调整为500MB。如果项目里有超过100MB的单个文件，调整缓冲可能还不够，更要考虑使用Git LFS管理大文件。个人项目遇到这类问题的概率不高，但一旦遇到，排查顺序就是：先看单个文件大小，再看文件总数，最后再看网络稳定性。
6. 这套流程为什么“其他也能用”，以及后续怎么扩展
6.1 核心是Git命令，不是Cursor
回头看整条链路：git init、git add、git commit、git remote add、git push，没有任何一个命令是Cursor专属的。
Cursor在这件事上扮演的角色是：
- 内置终端，省去了多窗口切换
- AI可以解释报错，减少卡住的时间
- 源代码管理面板，把Git命令包装成了按钮
但如果你把Cursor换成VS Code、IDEA、Zed，甚至换成纯终端，需要执行的命令完全一样。这就是“其他也能用”的真正含义。你学会的不是一个软件的操作，而是一套版本控制的思维方式。
6.2 换到其他环境时的等价操作
| 操作 | Cursor/VS Code | IDEA | 纯命令行 |
|---|---|---|---|
| 打开终端 | Ctrl+` | Alt+F12 | 直接在终端窗口cd到项目目录 |
| 查看改动 | 源代码管理面板 | Git工具窗口 | git status |
| 提交 | 面板按钮 | Commit按钮 | git commit |
| 推送 | 推送按钮 | Push按钮 | git push |
这里面最核心的是命令。图形化按钮只是把命令做了包装，点按钮失败时，最终还是要回到命令去看真实报错。
6.3 学会基础推送后，日常协作可以怎么扩展
第一次推送成功只是开始。之后你会逐渐遇到这些需求：
- 拉取线上最新代码：
git pull - 切换已有分支：
git checkout 分支名 - 创建新分支：
git checkout -b 新分支名 - 查看提交历史：
git log --oneline - 撤销未提交的修改：
git checkout -- 文件名
这些命令配合“提交-推送”主循环，基本能覆盖个人项目和小团队协作的日常。团队协作时，通常会以origin/main作为主线分支，每个人在自己的分支上开发，然后通过Pull Request合并主线。
我个人在教朋友用这套流程时的体会是：第一次传仓库，不用把Git所有概念都学会，只需要掌握“本地提交 -> 关联远程 -> 推送”这一个循环，先跑通一次，后面自然就知道要去学什么了。如果你在使用中报错，把错误信息直接发给Cursor的AI，让它结合当前仓库状态分析，比人肉搜报错要高效得多。踩过几次坑之后你会发现，Git的坑来来去去就那几个，无非是身份配置、分支名、文件忽略、token权限，提前把这些记住，后面基本畅通无阻。
最后分享一个小技巧：每次提交信息前，多花十秒钟想想“我这个改动到底做了什么”，写清楚一句人话。半年后再回来看提交历史，你会感谢当时养成这个习惯的自己。