1. 先建立正确的认知上传不是传文件而是同步提交记录1.1 GitHub 到底在帮你做什么很多人第一次接触 GitHub 是从上传代码开始的。你用 GitHub 下载过别人项目的源码觉得很简单等到自己要传代码上去却发现 git push 一执行就报错上网一搜全是零散的答案越看越乱。我在带新人时发现问题几乎都出在一个点上没有搞清楚 GitHub 的上传机制和传文件是两回事。GitHub 的核心不是网盘而是一个以 Git 为底层的代码托管平台。它管理的是提交记录而不是文件本身。也就是说你本地每做一次 git commit就是在项目历史里留下一个快照包括当时改了什么、谁改的、为什么改而 git push 是把这一串快照推送到远端仓库让 GitHub 上也拥有完整的历史。理解了这一点你就能明白为什么不能像往网盘里拖文件一样把代码扔上去也就能理解后面所有命令的顺序和意义。1.2 什么人最需要把这套流程彻底跑通这篇内容适合三类人完全没接触过 Git 的零基础新手已经会用 git clone 下载项目、但一上传就卡壳的人以及工作中需要把代码交给团队或开源项目、却总在认证和报错上浪费时间的人。我会按真实操作的顺序把从安装 Git 到日常更新代码的完整链路走一遍并把我踩过的坑和带新人时常遇到的问题一并写出来。上传代码这件事说穿了就是三句话在本地把项目初始化成一个 Git 仓库在 GitHub 上建一个空仓库把本地提交推上去。后面所有的报错、认证、分支问题都是这三句话的延伸。下面我不讲虚的直接按我自己的实操习惯来。2. 环境准备安装 Git 与全局配置的正确姿势2.1 各平台安装 Git 的差异在开始之前先确认你电脑上有 Git。检查方式很简单打开终端Windows 是命令提示符或 PowerShellmacOS 是 Terminal输入bash git --version如果能显示类似 git version 2.39.2 这样的输出说明已经装好了。如果提示找不到命令分平台处理Windows从 Git 官网git-scm.com下载 Windows 版本一路默认安装即可。装到Adjusting your PATH environment这一步时保持默认选项用Git from the command line and also from 3rd-party software。这个选项会直接把 Git 加入系统 PATH之后在 PowerShell 和 cmd 里都能直接用 git 命令。如果你之前装过但命令提示符里还是找不到关掉终端重新打开一次因为 PATH 环境变量要重启终端才生效。macOS最简单的是先试一下命令新版 macOS 会在你第一次输入 git 时自动引导安装 Xcode Command Line Tools。也可以用 Homebrew 装brew install git。装完同样用 git --version 验证。LinuxDebian/Ubuntusudo apt update sudo apt install gitCentOS/RHEL 系列用 sudo yum install git。这里有个常见的坑Windows 用户装完 Git 之后习惯性地去双击打开Git GUI或者右键点Git Bash Here这个操作没问题但我建议新手统一用终端操作因为网上所有教程的命令都是给你复制到终端运行的你在图形界面里对不上号反而更乱。老老实实用一个终端窗口把命令敲熟比什么都强。2.2 配置 user.name 和 user.email这一步影响你所有提交的署名Git 安装完还不能直接用它不知道自己是谁。每次提交代码时Git 都要往提交记录里写入作者信息所以要先把全局身份配置好bash git config --global user.name Your Name git config --global user.email your_emailexample.com配置里的 user.email 建议和你注册 GitHub 时用的邮箱保持一致。这不是形式主义——GitHub 会把提交记录里的邮箱和账号进行关联邮箱不一致的话你的提交虽然也显示在仓库里但不会关联到你的 GitHub 头像和主页看起来就像个陌生人的提交。想确认当前配置用bash git config --list看到 user.name 和 user.email 都正确第一步就算完成了。2.3 本地仓库的两种初始化方式上传代码之前本地必须有一个仓库。你可以简单理解为一个被 Git 管理的项目目录。初始化方式有两种对应不同的场景全新项目在一个空目录里执行 git init目录里会出现一个隐藏的 .git 文件夹这就是仓库的大脑所有提交记录、版本信息都存这里。注意把 .git 删掉项目就失去了版本历史变回普通文件夹。已有项目大多数人是先把代码写好了才想上传这种情况不需要重新建目录直接到项目根目录执行 git init 即可效果一样。后面我会专门演示这种已有代码目录的上传流程这也是最贴近实际需求的操作。3. 在 GitHub 上创建远端仓库那几个勾选项怎么选3.1 仓库名、可见性、初始化文件怎么填本地仓库准备好了远端也得有个接收方。登录 GitHub 后右上角点加号选 New repository新版界面里可能是 Create repository。这一步有几个选项新手经常纠结我按我的习惯解释一下Repository name仓库名。建议用 kebab-case 风格也就是全小写、单词之间用短横线连接比如 my-first-project。不要用中文也不要用空格Git 命令行工具对中文路径和空格的兼容性虽然比早年好很多但没必要给自己找麻烦。Description仓库描述可填可不填。填了会显示在仓库主页上开源项目最好填说明这个项目是干什么的。Public / Private公开还是私有。传代码练习、开源项目选 Public不想被外人看到或者公司项目选 Private。新手容易忽略的是改成 Private 只是别人搜不到、看不到你自己和被你授权的协作者还是能正常访问的。先不要勾选 Add a README file、Add .gitignore、Choose a license这三个是创建时自动生成的文件。如果你勾选了GitHub 上的仓库就有了初始提交而本地仓库还没有任何提交两边的历史对不上第一次 push 很容易触发冲突报错。最省心的做法是三个全不勾创建一个干净的空仓库。README 和 .gitignore 完全可以由自己在本地创建完再一起上传后面我会讲具体写法。3.2 绑定远端地址origin 到底是什么创建完成后页面会显示一个仓库地址通常有两种格式text https://github.com/用户名/仓库名.git gitgithub.com:用户名/仓库名.git前者是 HTTPS 地址后者是 SSH 地址。新手建议先复制 HTTPS 地址等后面弄懂了认证机制再切换 SSH。把远端地址和本地仓库绑定的命令是bash git remote add origin https://github.com/用户名/仓库名.git这里的 origin 是远端仓库的默认别名远端叫 origin是这个领域的通用惯例。之后你写 git push origin main意思是推送到那个叫 origin 的远端仓库的 main 分支。绑定完成后用 git remote -v 查看会列出当前仓库关联的所有远端地址确认一下别绑错了。我把绑错远端的坑多说一句我见过有人复制了别人的仓库地址比如刚从网上复制了一个开源项目的地址一 push 就提示权限不足。排查方式就是先运行 git remote -v如果显示的地址不是你自己的 GitHub 仓库用下面命令改回来bash git remote set-url origin https://github.com/你的用户名/你的仓库名.git4. 首次上传的完整命令链路add、commit、push 一个都不能乱4.1 初始化与添加文件git add 的粒度控制现在本地仓库有了远端仓库也有了中间只差一条推送通道。我用一个已写好的项目要上传的场景来演示你跟着敲一遍就能把整套流程跑通。假设我在 D:\work\my-project 目录里已经写好了一个 HTML 页面。操作如下bash cd D:\work\my-project # 进入项目目录 git init # 初始化本地仓库 git remote add origin https://github.com/用户名/my-project.git # 绑定远端然后把所有文件加入暂存区。Git 里有个概念叫暂存区你可以把它想成打包台git add 是把选中的文件放上打包台git commit 是把打包台上的东西封装成一个有编号、有时间、有作者的包裹提交。这样设计的好处是你可以灵活决定一次提交包含哪些文件而不是把目录里所有变动一股脑打包。bash git add . # 把当前目录下所有变动加入暂存区 git add index.html # 只暂存指定文件需要精确控制时用这个 git add src/ # 只暂存 src 目录下的变动git add . 是最常用的但有个注意点它会把你临时生成的、不该上传的文件也加进去比如本地的 .env 配置文件、IDE 的 .idea 目录、node_modules 之类。正确做法是先创建好 .gitignore 文件把不该上传的路径写进去再用 git add .。一个基础的 .gitignore 长这样gitignore node_modules/ .env .idea/ .DS_Store /dist/git add 之后用 git status 检查一下当前状态它会列出已经暂存的改动和尚未暂存的改动。养成 add 后必看 status 的习惯能避免把不该传的东西推上去这个习惯价值很大。4.2 提交记录commit message 怎么写才不被人骂确认无误后提交bash git commit -m 初始化项目添加首页-m 后面的内容是提交说明。不要随手写update或111这种没信息量的说明。规范的提交说明应该让三个月后的你自己以及你的同事一眼看懂这次改动做了什么。一般格式是动词 对象 补充比如修复登录页在移动端的样式错乱、添加商品列表的接口封装。如果提交说明写错了可以用 git commit --amend -m 新的说明 修正最近一次提交但这条命令改的是提交历史只在你还没 push 到远端时用比较安全。4.3 推送远端首次 push 的 -u 参数提交完成最后一步就是推送到远端bash git push -u origin main如果你的本地默认分支还叫 master先改成 main和 GitHub 保持一致省得以后在两个名字之间来回切换bash git branch -M main git push -u origin mainpush 成功后会显示一串输出大概长这样text Enumerating objects: 5, done. Counting objects: 100% (5/5), done. Writing objects: 100% (3/3), 271 bytes | 271.00 KiB/s, done. Total 3 (delta 0), reused 0 (delta 0) To https://github.com/用户名/my-project.git[new branch] main - main Branch main set up to track remote branch main from origin.看到 * [new branch] main - main 这行说明代码已经成功推到 GitHub。刷新仓库页面文件就都在了。这里的 -u 参数意思是把本地 main 分支和远端 main 分支建立跟踪关系以后只需要写 git push 或 git pull 就能自动对应到正确的远端分支不用每次带全参数。首次 push 建议带上后面日常更新就不用了。5. 认证方式为什么密码不行了以及 PAT 和 SSH 怎么选5.1 HTTPS PAT适合临时环境配置最快你可能会想push 的时候怎么没让我输密码这是因为不同环境行为不同——如果你用的是 HTTPS 地址push 时通常会弹出输入账号密码的窗口但你用 GitHub 账号的登录密码去填会提示认证失败。原因很简单GitHub 在 2021 年 8 月起就停止支持账号密码直接 push 了安全策略上强制使用更可靠的认证方式。目前主流的两种方式是 Personal Access Token个人访问令牌简称 PAT和 SSH Key。生成 PAT 的路径是GitHub 右上角头像 - Settings - 左侧最下面 Developer settings - Personal access tokens - Tokens (classic) - Generate new token。生成时勾选 repo 相关的权限范围如果只是上传代码勾选 repo 这个大类即可然后设置过期时间。GitHub 会给你一串以 ghp_ 开头的字符串这个值只在当前页面完整显示一次复制保存好关闭后就看不到了丢了只能重新生成。push 时提示输密码就输入这串 PAT而不是你的登录密码。如果不想每次都输可以配置 Git 的 credential helper在 Windows 上一般会自动保存。另外要提醒一句PAT 的权限就是一把钥匙勾选范围时给最小够用的权限就够了一旦代码传到公开仓库再发现令牌泄露第一时间去 GitHub 撤销并重新生成。5.2 SSH Key配置一次长期免密适合固定电脑如果你用的是自己的电脑我建议多用 SSH 的方式。先生成密钥对bash ssh-keygen -t ed25519 -C 你的邮箱example.com一路回车即可默认会在 ~/.ssh 目录下生成 id_ed25519私钥和 id_ed25519.pub公钥。私钥留在本地千万别外传公钥则是要交给 GitHub 的。查看公钥内容bash cat ~/.ssh/id_ed25519.pub把输出的整段内容复制到 GitHub 的 Settings - SSH and GPG keys - New SSH key 里粘贴保存。然后测试连通性bash ssh -T gitgithub.com第一次连接会提示确认主机指纹输入 yes 回车即可。看到类似 Hi 用户名! Youve successfully authenticated... 的输出说明配置成功。之后只要使用 gitgithub.com 开头的 SSH 地址push 和 pull 都不需要再输账号密码。5.3 两种方式的取舍对比项HTTPS PATSSH Key配置成本低生成令牌即可略高要生成密钥并配置公钥使用体验令牌有有效期可能过期一劳永逸安全性令牌泄露需手动撤销私钥泄露需重新生成并配置适合场景临时机器、公用电脑自己的主力电脑、长期开发我在实际带新人的过程中是这么建议的第一次操作、或者在公用电脑上用 HTTPS PAT省事自己长期用的电脑配好 SSH后面顺畅很多。两种方式可以同时存在不同仓库各自用不同地址就行。6. 高频报错排查从权限拒绝到推送失败上传代码这关报错是常态。我把自己被问得最多的几类错误整理出来按先定位问题类型再对症处理的思路写。遇到报错不要慌先读最后一行的英文提示很多时候答案就在里面。6.1 首次 push 被拒绝failed to push some refs这是首次上传时最经典的报错之一提示类似text ! [rejected] main - main (fetch first) error: failed to push some refs to https://github.com/用户名/仓库名.git原因就一句话远端仓库有本地没有的提交记录。最常见的触发场景是你在 GitHub 创建仓库时勾选了 README 或 .gitignore导致远端比本地多了一次提交。解决办法是先拉取合并再推送bash git pull --rebase origin main git push -u origin main--rebase 参数的作用是把本地提交接到远端提交之后让提交历史保持一条直线相比默认的 merge 合并更干净也不容易产生多余的Merge branch提交。新手只要记住提示 fetch first 就打这一套组合拳。6.2 权限与认证报错如果提示 remote: Permission to 用户名/仓库名.git denied或者是 fatal: Authentication failed分两种原因排查一是你 push 的仓库确实不属于你检查 git remote -v 看是不是绑错地址二是认证信息没配好HTTPS 方式下检查 PAT 是否过期、权限是否勾选齐全SSH 方式下检查公钥是否真的粘贴进了 GitHub。定位思路是先跑 ssh -T gitgithub.com 验证 SSH 是否通再跑 git remote -v 验证地址基本就能锁定问题。6.3 网络连接报错与大文件限制提示 fatal: unable to access https://github.com/... 或者 Failed to connect to github.com port 443说明本地根本没能和 GitHub 建立网络连接。常见原因包括公司网络策略限制、DNS 解析问题、系统代理设置残留。这类问题排查顺序是先试试浏览器能不能正常打开 GitHub如果浏览器都打不开那就是网络环境层面的问题如果能打开但命令行不通检查是否有代理环境变量影响了 git。GitHub 对单文件大小有限制超过 100MB 的文件会直接拒绝推送提示文件过大。而且 Git 的历史特性是一次提交永久存留哪怕你在下一个提交里删掉了大文件仓库里依然留有它的历史对象问题的清理会比较麻烦。所以上传前先检查项目里有没有超过几十 MB 的二进制文件如模型文件、打包产物、视频素材把它们排除在 Git 仓库之外。正经做法是用 Git LFSLarge File Storage管理大文件GitHub 对 LFS 也有免费额度如果只是临时需要也可以把大文件放到 Release 附件里不进入代码仓库。我在这里补一个排查时的通用习惯遇到报错先复制末行提示去搜索然后在本地按 git remote -v - git status - git log --oneline 的顺序检查三件套——远端地址对不对、工作区干不干净、本地提交有没有。80% 的上传问题在这三步里就能定位。7. 日常更新与协作不止上传一次就结束7.1 更新代码的正确顺序代码传上去只是开始。项目要持续迭代你后面离不开三个操作更新本地、推送改动、处理分支。我按日常节奏讲。每次改动前和改动后都建议先同步远端最新代码bash git pull origin main等你改完代码、add、commit 之后直接bash git push因为首次 push 时带过 -u本地和远端分支已经建立了跟踪关系所以不需要再写 origin main。这里有一个特别重要的习惯每次 push 之前先运行 git diff --stat 看一下本次改动了哪些文件、改动量大致多少再看一下 git status 确认没有把不该传的文件混进去。我见过不少事故都是 push 时才发现把数据库连接配置或者密钥文件传到了公开仓库。这个检查过程不到十秒钟但能省掉后面删提交历史的很多麻烦。7.2 分支操作先会用三条命令分支在 Git 里其实很轻量就是几个指针。日常协作中你只需要先会用三条命令bash git branch # 查看当前所有分支当前分支前面会有 * 号 git checkout -b dev # 新建并切换到 dev 分支 git push origin dev # 把本地 dev 分支推送到远端在 dev 分支上改完并提交再把 dev 推到远端然后在 GitHub 网页上发起 Pull Request简称 PR请求把 dev 合并到 main。这是开源项目和大多数团队的协作方式不直接在 main 上改而是开分支、提交 PR、经人 review 后合并。新手不用急着把所有概念都学全先把这三条命令用熟练工程的协作流程基本就顺畅了。7.3 冲突处理别怕看清三行标记就行当你和同事同时改了同一个文件的同一段代码后面 push 的人就会遇到冲突。Git 会把冲突标记写进文件长这样text HEAD 你这次改的内容别人改的内容分支名处理方式很直接打开文件把 、、 这三行标记连同不要的内容一起删掉保留你想要的最终结果然后重新 git add 和 git commit。注意在推送之前养成先 pull 的习惯可以显著减少冲突发生的次数。8. 网络连不上 GitHub 时的现实方案换一个仓库平台而不是硬扛这个问题比较现实也确实有不少人遇到代码写好了但 push 一直失败或者 GitHub 页面打不开。这里先把话说清楚如果你的网络环境访问 GitHub 长期不稳定我的态度很明确——不要在一个不通畅的平台上消耗大量精力换一个通路顺畅的代码托管平台才是性价比最高的选择。在国内最常见的替代平台是码云Gitee服务器在国内网络连接通常很稳定功能上覆盖了仓库管理、分支、PR、Issue 这些核心场景。迁移成本其实很低因为 Git 的机制是跨平台的同一个本地仓库可以同时拥有多个远端。我给个具体操作流程在 Gitee 上创建仓库获得一个地址比如 https://gitee.com/用户名/项目名.git。在本地仓库里把 Gitee 加为另一个远端命名随意但要能区分我习惯用 giteebash git remote add gitee https://gitee.com/用户名/项目名.git推送时指定 gitee 这个远端bash git push -u gitee main之后日常更新只需把 origin 换成 gitee 即可add 和 commit 那些步骤完全不用改。如果你的公司或团队用的是 GitLab思路一样git remote add gitlab 你的GitLab仓库地址再 git push -u gitlab main。掌握了一个本地仓库可以绑定多个远端这个概念你就能在任何 Git 平台上自如切换不被单一平台绑架。另外想提醒一句不要为了访问 GitHub 去使用来源不明的第三方工具或脚本这类工具往往需要读取你的 GitHub 账号数据存在账号被盗和代码泄露的风险。如果确实需要继续使用 GitHub更稳妥的办法是检查并修正本地的网络配置再从官方渠道获取帮助如果问题依旧就按上面的方案走 Gitee 或 GitLab同样能把项目完整跑起来。就我个人经验而言上传代码这件事80% 的精力其实花在前面 20% 的原理理解上。第一次把 add、commit、push 这套链路跑通之后后面每一天的推送代码就是三个命令的事。最后再把一个我一直强调的小习惯送给你每次 push 前看一眼 git status 和 git diff --stat确认自己在传什么这个习惯比任何命令都重要。