本文介绍了将本地项目首次推送到 GitHub/Gitee/GitLab 等远程仓库的完整流程。主要包含四个步骤：本地初始化、创建远程空仓库、关联并推送、验证成功。文章详细解释了 git init、add、commit、remote add、push 等命令的使用，强调了.gitignore 的重要性及分支命名规范。同时提供了常见错误（如历史记录冲突、密码认证失效）的解决方案，以及可视化工具推荐和最佳实践总结，帮助开发者避免新手陷阱。
你是否曾遇到过这样的场景：
node_modules、.idea 等无关文件也传上去了如果你有以上任何一点困扰，那么这篇教程就是为你准备的。我将把首次推送的完整流程拆解成 4 个不可颠倒的步骤，并附上每个步骤的详细解释和常见错误解决方案。
核心目标：让 Git 开始管理你的项目文件
# 1. 进入项目根目录
cd /path/to/your/project
# 2. 初始化 Git 仓库
git init
# 输出示例：Initialized empty Git repository in /path/to/your/project/.git/
# 此时会在项目目录下生成一个隐藏的.git 文件夹
# 3. 添加所有文件到暂存区
git add .
# 注意：这个"."代表当前目录所有文件，也可以指定具体文件
# 4. 提交到本地仓库
git commit -m "first commit"
# 提交消息要简洁明了，这里用"first commit"作为首次提交
关键点解析：
git init 只需执行一次，创建本地 Git 仓库git add . 中的点号代表当前目录及子目录所有文件（除了.gitignore 中忽略的）git commit 的 -m 参数必须跟上提交说明，否则会进入编辑器模式（新手容易卡在这里）核心目标：在代码托管平台创建一个'空房子'等待你的代码入住
| 平台 | 操作位置 | 特别注意 |
|---|---|---|
| GitHub | 点击右上角 + → New repository | 不要勾选 'Initialize this repository with a README' |
| Gitee（码云） | 点击右上角 + → 新建仓库 | 不要勾选 '使用 Readme 文件初始化这个仓库' |
| GitLab | 点击导航栏 + → New project | 不要勾选 'Initialize repository with a README' |
为什么不能勾选 README？
如果远程仓库初始化时有了 README 文件，它就不是空仓库了。当你推送时，Git 会发现本地和远程的历史记录不同，导致推送失败。需要先拉取合并，这对新手来说会增加复杂度。
核心目标：建立本地与远程的连接，并上传代码
# 1. 添加远程仓库地址（给远程仓库起个别名叫 origin）
git remote add origin https://github.com/yourname/yourrepo.git
# 这里把地址替换成你自己的仓库地址
# 2. 创建并切换到主分支（默认分支名可能是 master 或 main）
git branch -M main
# 如果本地默认是 master 分支，这行命令会把它改名为 main 并切换过去
# 3. 首次推送（建立跟踪关系）
git push -u origin main
# -u 参数表示建立本地分支与远程分支的跟踪关系
# 以后在这个分支上直接 git push 即可，无需指定远程和分支
关键点解析：
git remote add origin [地址]：origin 是远程仓库的别名，可以自定义，但大家都用origingit branch -M main：-M 是 --move --force 的缩写，强制重命名分支git push -u origin main：-u 是 --set-upstream 的缩写，只在第一次推送时需要核心目标：确认代码已安全到达远程仓库
命令行验证：
git status
# 应该显示：On branch main, your branch is up to date with 'origin/main'
git log --oneline
# 可以看到提交历史，确认提交已记录
如果你已经熟悉流程，或者想快速操作，这里有一条命令整合了所有步骤：
git init && git add . && git commit -m "init" && git remote add origin <仓库地址> && git branch -M main && git push -u origin main
注意事项：
<仓库地址> 替换成你的实际仓库 URL.gitignore 文件：你的'忽略清单'在第一步执行 git add . 之前，强烈建议创建 .gitignore 文件：
# 操作系统生成的文件
.DS_Store
Thumbs.db
# IDE 和编辑器配置
.vscode/
.idea/
*.swp
*.swo
# 依赖目录（根据你的项目类型）
node_modules/
__pycache__/
target/
build/
dist/
*.class
# 环境配置文件（不要上传敏感信息！）
.env
*.key
*.pem
创建方法：
# 在项目根目录创建.gitignore
echo -e ".DS_Store\nnode_modules/\n.env" > .gitignore
# 然后执行 git add . 和后续操作
现代 Git 的默认分支名发生了变化：
mastermain如何知道自己的 Git 版本？
git --version
git config --global init.defaultBranch
如果遇到分支名问题，可以这样处理：
# 如果本地是 master，想改为 main
git branch -M main
# 或者，如果远程希望用 master
git push -u origin master
你在 GitHub 上会看到两种仓库地址：
https://github.com/username/repo.git[email protected]:username/repo.git| 对比项 | HTTPS | SSH |
|---|---|---|
| 认证方式 | 用户名 + 密码/Token | SSH 密钥对 |
| 速度 | 较慢 | 较快 |
| 推荐场景 | 新手、临时使用 | 经常使用、追求效率 |
新手建议用 HTTPS，虽然每次推送需要输密码，但更简单。可以在 Git 中配置凭证存储：
git config --global credential.helper store
# 存储密码（谨慎使用）
src refspec main does not match any错误信息：
error: src refspec main does not match any
error: failed to push some refs to 'github.com:xxx/xxx.git'
原因分析：
git commit）解决方案：
# 1. 确认本地有提交
git log
# 如果显示 fatal: your current branch 'main' does not have any commits yet
# 说明确实没有提交
# 2. 执行提交
git add .
git commit -m "initial commit"
# 3. 再次推送
git push -u origin main
failed to push some refs to ...错误信息：
! [rejected] main -> main (fetch first)
error: failed to push some refs to 'github.com:xxx/xxx.git'
hint: Updates were rejected because the remote contains work that you do not
hint: have locally. This is usually caused by another repository pushing to
hint: the same ref. You may want to first integrate the remote changes
hint: (e.g., 'git pull ...') before pushing again.
原因分析：
远程仓库不是空的（最常见的是创建时勾选了 README）
解决方案：
# 方法 1：拉取远程内容并合并（推荐）
git pull origin main --allow-unrelated-histories
# --allow-unrelated-histories 允许不相关的历史合并
# 然后解决可能的冲突，再推送
git push origin main
# 方法 2：强制推送（谨慎使用）
git push -f origin main
# -f 是 --force 的缩写，会覆盖远程历史
# 注意：如果团队其他人在这个仓库有工作，不要用这个方法！
support for password authentication was removed错误信息：
remote: Support for password authentication was removed on August 13, 2021.
remote: Please see https://docs.github.com/en/get-started/getting-started-with-git/about-remote-repositories#cloning-with-https-urls
原因分析：
GitHub 从 2021 年 8 月起不再支持账号密码验证
解决方案：
# 方法 1：使用 Personal Access Token（PAT）
# 1. 在 GitHub → Settings → Developer settings → Personal access tokens 生成 token
# 2. 推送时用 token 代替密码
git push -u origin main
# 用户名：你的 GitHub 用户名
# 密码：刚才生成的 token（不是登录密码！）
# 方法 2：使用 SSH 密钥
# 1. 生成 SSH 密钥：ssh-keygen -t ed25519 -C "[email protected]"
# 2. 添加到 GitHub：Settings → SSH and GPG keys
# 3. 修改远程地址为 SSH 格式
git remote set-url origin [email protected]:username/repo.git
# 4. 再次推送
Updates were rejected because the tip of your current branch is behind错误信息：
! [rejected] main -> main (non-fast-forward)
error: failed to push some refs to '...'
原因分析：
远程有新的提交，而本地没有拉取更新
解决方案：
# 先拉取更新
git pull origin main
# 如果有冲突，解决冲突后提交
git add .
git commit -m "merge remote changes"
# 再推送
git push origin main
如果你对命令行感到恐惧，可以使用可视化工具：
开始
↓
本地初始化 (git init/add/commit)
↓
远程仓库是否为空？
├─ 是 → 关联远程并推送 (git remote add/push -u)
│ ↓
│ ✅ 推送成功
│ ↓
│ 结束
└─ 否 → 选择解决方案
↓
拉取合并 (git pull --allow-unrelated-histories)
或
强制覆盖 (git push -f) ⚠️慎用
↓
解决冲突并提交
↓
验证结果
↓
结束
git push当你掌握了首次推送后，可以进一步学习：
git branch, git checkout, git mergegit reset, git revert, git checkout --git stashgit log的各种用法
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML 转 Markdown 互为补充。 在线工具，Markdown 转 HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML 转 Markdown在线工具，online
通过删除不必要的空白来缩小和压缩JSON。 在线工具，JSON 压缩在线工具，online
将JSON字符串修饰为友好的可读格式。 在线工具，JSON美化和格式化在线工具，online