最近好几个朋友都在问我同一个问题在Linux上写好的项目怎么才能推到GitHub上其实单独讲Git命令网上教程一抓一大把但真到自己上手操作还是会卡在各种报错和概念混淆上。最常见的情况是命令敲完了提示成功可网页上什么都没有或者明明还是同一台机器第二天再push却提示权限不对。这篇东西就从我实际使用的角度把Linux环境上传GitHub的完整过程从头到尾捋一遍重点讲清楚每条命令为什么要这么写、每个报错到底在说什么新手跟着操作完基本能跑通已经有点基础的朋友也可以对照查漏补缺。1. 项目概述一次上传背后到底发生了什么1.1 这个标题想解决什么问题Linux上传GitHub本质上是一条很典型但很完整的开发链路。你很可能在Linux上写代码、做实验、搭服务代码放在本地没问题但本地文件一旦误删、硬盘损坏或者想换一台设备继续开发就很被动了。GitHub解决的是“远程托管”这件事。Git是版本控制工具负责在你本地记录、管理每一次文件变化GitHub则是基于Git的远程仓库平台相当于把存好档案的文件夹放到一个大家都能访问的服务器上。二者关系可以这样理解Git是“存档系统”GitHub是“远端保险柜”。“上传”这个动作表面看只是把文件复制过去实际做的是把本地Git仓库和远程GitHub仓库建立关联然后把本地这些存档记录一并推送过去。这个理解到位了后面所有命令都不会觉得是死记硬背。1.2 为什么选择命令行而不是图形界面很多刚接触Linux的朋友会觉得Linux上没有GitHub Desktop是不是就不好操作了实际上恰恰相反。在Linux上命令行才是Git最舒服的使用方式。一是在服务器环境里基本没有图形界面你迟早要面对终端二是命令行返回的每一条提示都是排查问题的重要线索图形界面把这些底层信息藏掉之后一旦出错反而更难办。还有一个现实原因绝大多数云服务器、开发容器里只有一个纯终端命令行操作是通用方案。学会之后无论是本机还是远程服务器都能用同一套流程处理不需要依赖任何桌面环境。所以这篇内容全程在终端里操作不涉及GUI工具。1.3 传输方式选型SSH比HTTPS省心在哪里GitHub支持HTTPS和SSH两种方式与远程仓库通信。HTTPS地址形如https://github.com/用户名/仓库.gitSSH地址形如gitgithub.com:用户名/仓库.git。两者的差别关键在于身份认证HTTPS每次push会要求输入GitHub的用户名和密码而且现在GitHub已经不再接受单纯密码需要生成Personal Access Token来替代处理起来多一道工序SSH则是在本地生成一对密钥把公钥放到GitHub后台之后再push就不需要反复认证。结论很清楚第一次配置时多花两分钟搞SSH后面每个仓库都省心。这也是我在这篇里推荐的方式。1.4 核心链路从本地到远程的完整动作整个流程可以拆成下面八个步骤后面所有操作都是围绕这条线展开的安装Git并配置用户信息。生成SSH密钥并把公钥加到GitHub账号。在GitHub上创建一个空仓库。在本地项目目录执行git init。用git add将文件加入暂存区。用git commit生成一次本地提交。用git remote add关联远程地址。用git push推送到远程。心里先有这条框架遇到问题就能快速定位到具体环节排查起来不会一团乱麻。2. 环境准备装Git、配身份、生成SSH密钥链路清楚之后就开始搭环境。这里多说一句环境准备这件事不要嫌麻烦密钥和身份信息配好了后面所有仓库都能用属于一次投入长期收益的事。2.1 不同Linux发行版的Git安装方法“git”这个命令有些Linux发行版默认装好了有些没有。最简单的判断方式是直接输入git --version如果能输出版本号就说明已经可用如果提示Command not found就需要自己安装。不同发行版用的包管理器不一样常用命令如下Debian/Ubuntu系列sudo apt update sudo apt install git -yCentOS/RHEL系列sudo yum install git -yFedora系列sudo dnf install git -yArch/Manjarosudo pacman -S git安装完成后再次执行git --version确认版本号能正常输出就说明环境没问题。顺便提醒一句如果你用的是刚装好的Linux建议先保证系统时间准确尤其是服务器上时间偏了容易出现一些很奇怪的网络类疑难问题后面排查起来非常耗时间。2.2 配置用户信息这一步为什么不能省Git每次提交时会把用户信息记录在commit里所以需要先告诉Git你是谁。执行下面两条命令git config --global user.name 你的名字 git config --global user.email 你的邮箱--global表示对当前用户的所有仓库生效。如果某个仓库需要单独身份可以进入仓库目录后不加--global重新设置。用git config --list可以把当前所有配置列出来检查一下有没有写错。有一点很容易忽略GitHub查看提交历史时主要通过邮箱把提交关联到账号上所以建议填你注册GitHub时用的邮箱否则页面上显示的头像和commit归属会不对。填错了或者有多个邮箱后期改起来比较麻烦。这一步很基础但直接影响你代码提交的“署名”值得认真对待。2.3 生成SSH密钥并绑定到GitHub账号先确认之前有没有生成过密钥执行ls -al ~/.ssh。如果这个目录里已经有id_ed25519或id_rsa这类文件可以直接复用如果没有生成新的ssh-keygen -t ed25519 -C 你的邮箱关于算法选择ed25519是目前GitHub推荐的算法密钥短、安全性好。如果你需要兼容一些比较老旧的环境可以用RSAssh-keygen -t rsa -b 4096 -C 你的邮箱生成的时候直接按回车使用默认路径即可。中间会提示设置passphrase可以理解为给私钥再加一道密码。如果你的机器只有自己用直接留空也可以办公机器建议设置安全一点。生成完后会有两个文件id_ed25519是私钥千万不能外泄也不要提交到Git仓库id_ed25519.pub是公钥就是下一步要添加到GitHub的内容。查看公钥用cat ~/.ssh/id_ed25519.pub把输出的内容完整复制下来多复制到回车符也没关系GitHub会自动去掉首尾空白。记住私钥文件不该给别人不该上传到代码仓库谁拿到你的私钥就相当于拿到了你的写入权限。2.4 测试连通性ssh -T这一行的准确含义打开GitHub网页登录后进入Settings在左侧找到SSH and GPG keys点击New SSH key。Title随便填一个能认出来的名字比如“我的Linux笔记本”Key框里粘贴刚才复制的公钥最后点击Add SSH key保存。回到Linux终端执行ssh -T gitgithub.com如果你是第一次连接GitHub会看到如下提示The authenticity of host github.com (...) cant be established.输入yes回车即可它的意思是让你确认这是一台你信任的主机。输入yes后这个确认会记录在known_hosts文件里下次不会再问。如果看到Hi 用户名! Youve successfully authenticated, but GitHub does not provide shell access.就表示密钥已经生效可以进入下一步了。如果提示Permission denied回到上面检查公钥是否复制完整、是否保存到了正确的账号下。3. 首次上传实操从新建仓库到成功push环境准备好了下面真正开始上传。假设你的项目目录叫my-project位于/home/用户名/my-project后面的命令都以这个目录为例。3.1 在GitHub上创建一个正确的空仓库登录GitHub后页面右上角有个号点击后选择New repository。Repository name填项目名建议全小写英文用短横线分隔单词比如my-project这样的名字在命令行里更好处理。Visibility选择Public或者Private公开仓库任何人都能看到私有仓库只有你和你邀请的人能看初学者按需选择就好。这里重点提醒如果你不打算先下载再补代码就不要勾选Add a README file、Add .gitignore、Choose a license这三项。因为这些选项会让GitHub在初始化时自动生成一个或多个提交而本地仓库还没有任何内容两边没有共同历史后面第一次push时会被直接拒绝。处理起来不少麻烦。完全空白的仓库创建好之后GitHub会显示如何用命令推送的提示这个提示稍后会用到。3.2 本地初始化与第一次提交进入项目目录cd /home/用户名/my-project先确认当前目录里有项目文件可以pwd看路径ls看文件列表避免在错误目录初始化。然后执行git init这个命令会在当前目录下创建一个.git目录里面存放整个仓库的版本数据。建议用git status看一下状态这时你会看到一堆Untracked files意思是你还没有把这些文件纳入Git版本管理。接着执行git add .注意这里的点号表示“当前目录下所有文件”add的作用是把这些文件从工作区放入暂存区。如果你只想添加某个文件可以写成git add main.py。添加结束后再git status文件会从Untracked变成Changes to be committed在终端里以绿色显示。这一步还有一个重要检查点滚动一下status的输出确认准备提交的文件里没有密码、私钥、大数据文件之类不该进仓库的东西。万一有先写.gitignore再继续不要心存侥幸。我曾经见过有人把数据库连接密码直接提交到公开仓库后面撤回重写历史非常痛苦。3.3 关联远程仓库并推送回到GitHub上刚创建的仓库页面复制SSH地址形如gitgithub.com:你的用户名/my-project.git。在终端执行git remote add origin gitgithub.com:你的用户名/my-project.gitremote是“远程仓库”的意思origin是这个远程仓库在你本地起的默认名字。可以把它理解为“那个远方仓库”的别名后面所有跟远程打交道的命令都用origin来指代这个仓库方便很多。关联后检查一下git remote -v如果输出了fetch和push两条地址说明关联成功。然后执行git branch -M main这条命令把当前分支重命名为main。GitHub新仓库默认主分支叫main而很多老版本Git默认用master这里统一一下避免推送时分支对不上。最后执行git push -u origin main-u参数的作用是建立“本地main分支跟踪远程main分支”的关系以后直接git push就能推送不需要再带origin main。push过程中如果看到类似Username for https://github.com的提示说明远程地址用的是HTTPS而非SSH可以用git remote set-url origin gitgithub.com:你的用户名/my-project.git改成SSH地址。push成功后终端会显示文件数量、速度等统计信息。刷新GitHub页面代码就出现在仓库里了。3.4 推送成功后的二次验证上传成功并不是只看终端那几行字建议做两个验证。一个是本地执行git log --oneline确认提交记录存在另一个是直接刷新GitHub网页。如果网页上能看到代码同时又能看到commit记录说明这次上传是彻底的、可访问的。还有一个容易误会的地方push之后如果再修改本地文件网页不会自动变化必须重新git add、git commit、git push这个节奏后面会反复用到。4. 日常更新与进阶用法不只是会push第一次上传跑通之后你其实已经完成了最重要的一步。之后的日常使用就是围绕“改代码 — 提交 — 推送”这个循环展开。4.1 标准提交节奏与查看改动的技巧日常更新其实就三条命令git add . git commit -m 这次改了什么 git push第一步要把改动放进暂存区第二步生成一条提交记录第三步推到远程。由于第一次push用了-u后面直接git push即可。提交前想看清楚自己改了什么东西可以用git diff它会以类似补丁的形式显示本次改动git diff --cached则查看已经放进暂存区的内容。这个习惯很好提交前先看一眼能避免把调试代码、无关文件一起打包提交。commit信息不要写得太随意比如update这种别人看不明白。最好写清楚例如fix: 修复登录接口空指针异常、feat: 新增用户注册功能。几个月后回看git log每条记录都能快速定位当时的改动意图这对项目维护非常重要。4.2 .gitignore的用法和常见规则项目里不是所有文件都应该进Git。比如Python项目中的__pycache__目录、*.pyc文件、.env环境变量文件、虚拟环境venv目录C/C项目编译出来的.o、build目录日常使用中常见的.log日志、.DS_Store系统文件这些要么是生成物要么含敏感信息不该上传。解决办法是在仓库根目录建一个.gitignore文件里面写忽略规则__pycache__/ *.pyc venv/ .env build/ *.log .DS_Store每行一个规则写完后把.gitignore提交一次。之后再git add .时被忽略的文件就不会进入暂存区。有一点要特别注意如果文件已经被Git跟踪比如你已经提交过.env那现在把它写进.gitignore并不会让它停止跟踪。需要先执行git rm --cached .env把文件从暂存和管理列表中移除但保留磁盘文件然后再提交。这个细节很多人栽过跟头工作里也经常遇到提前处理好能省去不少麻烦。4.3 分支、标签和README的实践建议分支是Git非常强大的功能也是新手进阶绕不开的一环。最常用的几条命令git branch # 查看当前有哪些分支 git checkout -b dev # 新建并切换到dev分支 git push origin dev # 把dev分支推送到远程 git checkout main # 切回main分支 git merge dev # 把dev分支的改动合并到main建议的用法是main分支保持一个相对稳定的状态新功能或实验性改动放到独立分支上测试没问题再合并回main。这样即使某次改动出了问题主干代码依然可以正常使用。发布正式版本时可以用taggit tag v1.0.0 git push origin v1.0.0标签会把当前commit标记为一个特定版本。之后在GitHub仓库页面的Releases里可以基于标签创建发布说明别人就能很方便地下载这份源码的打包文件比直接给仓库链接更规范。另外强烈建议为仓库写一个 README.md。用简单的文本说明项目是干什么的、怎么跑起来、依赖什么环境。这是GitHub仓库的门面也是你自己的“说明书”。后面换设备重新拉代码的时候看一眼README就能快速想起来项目的来龙去脉非常有用。4.4 多设备同步clone、pull与冲突处理如果你的工作会换机器比如办公室一台电脑家里一台那么GitHub刚好充当了中间的同步中枢。在新机器上第一次获取代码git clone gitgithub.com:你的用户名/my-project.gitGit会自动把远程仓库完整克隆到当前目录。进入目录后正常改代码结束时照常add、commit、push。下次在这台机器继续工作前先执行git pull把远程的最新提交拉到本地。因为可能有另一台机器push了新内容如果你直接在旧版本基础上改再push时会被拒绝因为远程已经领先于本地。正确做法是先pull再开发最后push形成一个不会冲突的循环。如果pull时出现冲突Git会在文件里插入冲突标记类似 HEAD、、 origin/main。你需要手动打开文件保留正确内容删掉这些标记再add、commit、push。处理冲突是Git使用中的必修课第一次会有点慌多处理几次就好。5. 常见问题与排查技巧实录前面流程走完大部分场景已经够用了。这里把实操过程中容易踩的坑集中整理一下按照“报错 — 原因 — 解决”的方式列出来排查的时候直接对照着看。5.1 高频报错速查表报错现象可能原因解决办法Permission denied (publickey)SSH公钥没添加到GitHub或ssh-agent没有加载密钥cat ~/.ssh/id_ed25519.pub确认已在GitHub后台添加执行ssh-add ~/.ssh/id_ed25519后重试remote origin already exists当前仓库已经关联过一个远程地址git remote remove origin再git remote add origin 新地址或直接git remote set-url origin 新地址error: failed to push some refs远程仓库有本地没有的提交最常见是远程初始化了README先git pull origin main --allow-unrelated-histories解决冲突后再pushfatal: repository ... not found仓库地址错误、仓库是私有的但当前账号无权限git remote -v看地址是否正确检查仓库可见性和登录账号The authenticity of host github.com cant be established第一次使用SSH连接需要确认主机指纹输入yes回车把主机加入known_hostsfatal: refusing to merge unrelated histories本地和远程没有共同提交历史git pull origin main --allow-unrelated-histories合并后push5.2 排查问题时的调试思路遇到问题不要盲目到处搜先按链路排查。第一条命令永远是git remote -v确认自己没有关联错仓库再执行ssh -T gitgithub.com确认密钥能不能连通。如果SSH有问题就看~/.ssh目录下有没有密钥文件、公钥是否在GitHub后台。如果仓库地址和密钥都对那再考虑分支问题比如远程是不是有别的分支抢跑了。还有一个比较深入的调试方法在命令前加GIT_SSH_COMMANDssh -v比如GIT_SSH_COMMANDssh -v git fetch这样能看到SSH连接的详细日志能帮你定位到具体是哪一步失败。这个方法平时用不到但真遇到疑难问题时会省很多时间。5.3 中文文件名乱码的处理方法在Linux下处理从Windows传来的压缩包时中文文件名乱码很常见。这个问题的根源在于压缩包内文件名的编码和当前系统不一致Windows下常见zip会使用GBK编码而Linux默认UTF-8解压出来就会乱码。一个比较直接的解决办法是用下面这条命令解压让unzip按指定编码解析文件名unzip -O GBK 文件名.zip如果你的系统里没装unzip可以用对应包管理器安装。另外即使文件已经解压进来只要文件名在终端里能正常显示通常上传GitHub就不会出问题。如果想把乱码文件名批量改正确可以先ls看一下实际显示再用mv命令逐个改名。这里强调一点先确认文件名正常再add和commit因为一旦把乱码文件名提交进去后面改起来还要多一步。5.4 页面访问不稳定的应对建议经常会有人问GitHub网页打不开或者clone速度很慢。我的经验是先别急着怀疑命令和配置问题可以先curl -I https://github.com看看基础连通性或者直接换个时间段、换个网络环境再试。如果项目对稳定性要求比较高一个很常见的做法是把仓库同时同步到一个国内代码托管平台上比如Gitee然后让GitHub作为主要发布渠道、国内平台作为同步备份。这样既不影响你在GitHub上的开源展示日常拉代码也多了一条路。这里不涉及什么特殊网络技巧但把备份和同步机制做起来实际使用中反而比临时折腾网络更可靠。按照我个人在Linux上操作GitHub几年的经验这套东西真正难的不是命令而是理解“本地提交、远程关联、推送同步”这个过程。只要思路顺了哪怕换一台全新的电脑照着链路走一遍也能很快上手。最后再分享一个小习惯第一次配好SSH之后建议把~/.ssh/config整理一下比如给常用主机起一个方便记忆的别名以后用起来会顺手很多。配置本身不复杂但能让日常操作省下不少时间。如果这篇内容能帮你在Linux上少踩几个坑那就很值了。