GitHub代码分享实战：仓库创建、大文件处理与报错排查

把代码放到GitHub上这件事，听起来像是程序员的基本功，但真到了自己动手的时候，不少人都卡在了一些意想不到的地方。有的卡在“github怎么上传文件夹”，有的卡在push的时候报错，还有的折腾半天发现单文件超过100MB根本传不上去。我见过太多人把GitHub当成一个普通的网盘，拖拽上传完事，结果仓库乱成一团，过两天自己都看不懂。也有很多人问我要大文件的处理方案，因为GitHub默认拒绝超过100MB的单个文件，超过50MB还会弹警告，这些问题不提前搞清楚，迟早会在某个加班的深夜突然找上你。

这篇文章我不打算写那种官方文档式的教程，而是按我实际用下来的经验，把“在GitHub上分享代码”这件事拆开揉碎。从最基础的仓库概念讲起，到本地代码怎么推上去，再到带大文件的项目怎么处理，最后聊一聊上传过程中那些奇奇怪怪的报错和排查思路。无论你是第一次用GitHub的学生，还是已经写过一阵子代码但没系统整理过仓库的开发者，这篇文章应该都能让你少走点弯路。

1. 分享代码之前，先搞懂GitHub仓库的工作方式

很多人第一次打开GitHub，界面是看得懂的，Create repository那个按钮也很显眼，但“仓库”这个概念到底意味着什么，其实没几个人真的想清楚了。GitHub上的一个仓库，表面上看就是一个文件夹，能装代码、能存文档，但它背后是一套完整的版本管理逻辑。你在本地写的代码，经过Git这个工具的管理，推送到远程仓库里，别人才能看到。这里的关键点是：GitHub不是简单的文件存储，它记录的是每一次变更的历史。

1.1 仓库（Repository）到底是什么

拿一个实际项目举例。假设你在本地有一个Python脚本文件夹，里面有main.py、requirements.txt、README.md。如果不做任何版本管理，这个文件夹就只是一个文件夹，你改了代码，原来的版本就被覆盖了，想回退都难。而当你把它初始化成一个Git仓库之后，每一次提交（commit）都会像拍快照一样记录当时的文件状态。GitHub上的远程仓库，本质上是这些本地快照的云端备份和展示平台。

这里有个非常容易被忽略的认知：你在GitHub网页上看到的文件列表，其实是某个时间点的“快照”，而不是实时同步的。本地改了代码，必须执行git push，远程仓库才会更新。很多新手直接在网页上点Upload files上传，虽然能成功，但本地和远程就变成了两套互不相干的东西，越往后越混乱。

1.2 GitHub上分享代码的两种常见路径

在实际使用中，我见过两类人。一类是代码纯托管型，就是想把写好的东西放到网上，给朋友看看或者留个备份，这类人用网页上传就够了。另一类是持续开发型，本地写完代码要频繁更新，甚至多人协作，这类人必须走完整的Git命令行流程。

如果只想分享一次，网页上传没毛病。但只要你打算持续维护这个项目，哪怕只是每周更新一次，我也建议你从一开始就习惯用Git命令行。这就像写文档，你可以在记事本里写，但迟早要迁移到支持版本管理的工具里，差别只在迁移的时机和成本。

2. 从零到一：创建仓库并完成首次代码提交

讲完了理念，进入实操。这一节我按自己最常用的流程走一遍，从在GitHub网页上创建仓库，到本地初始化、提交、推送到远程，中间会标注那些我踩过的坑。

2.1 创建仓库时这几项设置最容易踩坑

在GitHub右上角点击“+”号，选择“New repository”，会进入仓库创建页面。仓库名建议用英文小写加连字符，比如my-first-project，别用中文和空格，否则后续URL拼接和本地目录映射都会出问题。描述（Description）可以填一句话说明项目用途，这个会显示在仓库页面的顶部，建议认真写。

创建页面里有一个“Initialize this repository with a README”的选项，很多教程会让你勾选，但我个人建议：如果你打算从命令行推送本地已有的代码，千万别勾选。一旦勾选了，远程仓库就会自动生成一个README文件，而你本地是空的，推送的时候一定会遇到冲突。如果远程仓库有文件而本地没有，Git默认会拒绝合并，报出fatal: refusing to merge unrelated histories之类的错误。虽然可以用--allow-unrelated-histories强制合并，但对新手来说完全是增加负担，不如一开始就不要勾。

同理，.gitignore和license也建议先不选，等本地代码推上去之后再补，或者直接在本地创建好再推。这样可以保证远程仓库的第一个提交就是你本地代码的初始状态，干净利落。

2.2 本地代码推到GitHub的完整命令流程

假设你本地有一个项目文件夹my-first-project，里面有若干代码文件。打开终端（Windows用Git Bash，macOS/Linux直接Terminal），按顺序执行以下命令：

cd path/to/my-first-project git init git add . git commit -m "Initial commit" git branch -M main git remote add origin https://github.com/你的用户名/my-first-project.git git push -u origin main

逐条解释一下每条命令的用途。git init把当前文件夹变成Git仓库，这时会在文件夹内生成一个隐藏的.git目录，你的所有版本记录都存在这里。git add .把当前目录下所有文件加入暂存区，注意这里有个点号，表示全部文件；如果你只想提交特定的文件，可以用git add 文件名。git commit -m "Initial commit"把暂存区的内容固化成一次提交，-m后面是提交说明，这是给未来的自己或协作者看的，写清楚点好。

git branch -M main是把当前分支改名为main。GitHub默认分支名是main，但老版本Git初始化出来的仓库默认分支可能叫master，不改名直接推送会出问题。

git remote add origin是把本地仓库和远程仓库建立关联，origin是远程仓库的别名，之后推送、拉取都会用到这个名字。后面的URL从GitHub仓库页面可以复制，通常有HTTPS和SSH两种格式，新手推荐HTTPS，虽然每次推送都要输账号密码（准确说是Personal Access Token），但配起来简单。

最后的git push -u origin main是推送到远程分支，-u参数会把本地分支和远程分支关联起来，以后直接敲git push就能推。

很多人在这里会遇到认证失败的问题。原因很简单：GitHub早就停止支持账号密码认证，现在必须使用Personal Access Token，或者配置SSH密钥。我在第一次配置的时候也被卡了很久，后来找到了办法：在GitHub的Settings -> Developer settings -> Personal access tokens里生成一个token，赋予repo权限即可。推送的时候把密码位置粘贴这个token，就能正常提交了。

3. GitHub上传大文件：绕不开的边界问题

终于聊到大文件了。每次有人咨询我GitHub的问题，十个里有八个是问“我的模型文件传不上去怎么办”“数据集太大怎么办”。这时我都会先问一句：你知道GitHub对单文件大小的限制吗？大部分人都知道有100MB这个数字，但具体的细则是模糊的。

3.1 GitHub对文件大小到底限制多少

先看一张我整理的对照表：

关键点在于，GitHub的限制是单个文件不超过100MB，而不是整个仓库大小。仓库的总大小没有硬性限制，但超过1GB会收到官方建议邮件，建议你使用Git LFS或Release。顺便提一句，即使单个文件恰好是99MB，push上去之后整个仓库的克隆体验也会很差，因为每次克隆都要下载完整的历史版本，仓库体积会随时间膨胀。

3.2 哪些场景会遇到大文件问题

大文件通常集中在这么几类：训练好的深度学习模型权重（常见的.pth、.h5、.onnx文件动辄几百MB）、数据集（尤其是图片和视频样本）、前端打包产物（打包后的dist目录里可能有超过100MB的JS或图片资源）、游戏开发里的资源包、压缩包和安装包。如果你做的项目涉及这些，迟早会撞上这个限制。

还有一个冷知识：如果你在历史提交里曾经加入过一个大文件，后来删掉了，再push仍然会失败。因为Git记录的是整个历史版本，那个大文件依然存在于你本地的.git目录里。我遇到过一个情况，新手把600MB的压缩包加了进去，然后发现传不上去，在本地删掉就完事了，结果第二次push还是报同样的错。原因是那个文件还留在历史提交里。解决的办法要么是git commit --amend修改上一次提交，要么用git filter-branch重写历史，要么干脆重新初始化仓库。对新手来说，最省事的方案是：把.git目录删掉，重新git init，再重新提交一遍，前提是你不在乎历史记录。

4. 大文件上传的三条可行路线：LFS、Release、外部存储

遇到大文件别慌，GitHub给了你好几条路，只是官方文档把信息拆得太散，没人系统讲清楚。我根据自己的项目实践，梳理出三条最实用的路线，它们的适用场景完全不同，选错了会非常痛苦。

4.1 路线一：Git LFS跟进超大文件

Git LFS（Large File Storage）是GitHub官方提供的大文件管理方案，它解决的核心问题是：不能用Git的普通机制追踪大文件。LFS的做法是，把大文件的实际内容存到独立的存储空间里，仓库里面只放一个文本指针，指向那个内容的地址。这样仓库本身保持轻量，克隆速度不会被拖垮。

使用LFS的流程不复杂。先安装Git LFS插件，然后在项目根目录执行：

git lfs install git lfs track "*.pth" git add .gitattributes git commit -m "Add .pth file tracking via LFS"

这里有个细节非常重要：git lfs track "*.pth"会在项目里生成一个.gitattributes文件，里面记录了哪些类型的文件要用LFS管理。这个.gitattributes文件本身必须提交到仓库里，否则其他人克隆你的项目时，就不知道这些文件应该走LFS，会直接当成普通文件，导致仓库异常膨胀。

之后你就可以像提交普通文件一样提交大文件了，但底层逻辑是完全不同的。LFS有一个免费额度：仓库本身的存储空间1GB，每月带宽1GB。对于一般的小项目，这个额度足够用。如果不够，需要在GitHub上购买数据包，价格不算离谱，但也不是免费的。

实际使用中LFS有个体验问题：克隆时需要额外从LFS服务器拉取大文件，如果你的网络状况不好，克隆的时候可能会卡很久，而且LFS下载不支持断点续传，中断了就得重来。所以我的建议是：不到万不得已，不要用LFS来存模型权重或数据集这种几百MB的大家伙，它更适合管理偶尔更新、体积在几十MB到一两百MB之间的资源文件。

4.2 路线二：GitHub Release做版本化分发

如果你要分享的不是项目源码，而是编译后的安装包、模型权重、压缩文档，那最合适的其实是GitHub Releases功能。Release是GitHub专门用来做版本化发布的，每个Release可以关联一个Git标签（Tag），同时可以上传任意数量的附件文件，单文件上限是2GB，比仓库本身的限制宽松得多。

我的习惯是这样的：代码照常通过Git推送，但像模型权重这种生成物，不放进仓库，而是在每次发布正式版本时，通过Release页面手动上传，或者用GitHub Actions自动构建并附加到Release里。这样做的好处非常明显：仓库保持干净，克隆速度快，别人想要模型文件，直接在Release页面下载，不会误操作把大文件拉进仓库。

具体操作是在仓库页面的Releases一栏，点击“Draft a new release”，填一个版本号（比如v1.0.0），写好发布说明，然后把大文件拖拽到附件区，发布即可。后续维护也很方便，旧版本的文件会一直保留，别人可以按需下载。

4.3 路线三：外部对象存储放成品文件

Release的2GB限制对绝大多数场景都够用了，但如果你的文件超过了2GB，那就必须把文件放到外部存储上，然后在README或者Release说明里附上下载链接。比较常用的选择是各大云厂商的对象存储服务，一般来说按量付费，一个月几GB的流量也花不了多少钱。把文件传到对象存储后，生成一个分享链接，写到README或Release说明里就行。

这里有一个很重要的经验：外部链接一定要写清楚文件用途和获取方式，而且最好用做版本号路径。比如https://your-bucket.example.com/model/v1.0.0/weights.pth，这样即使是几个月后再回来看，也能一眼知道这个文件是哪个版本的。我见过有人在README里丢一个过期链接，半年后别人下载，404了，影响非常不好。

如果你觉得对象存储麻烦，网盘的分享链接也可以用，但要注意有效期和可达性问题，毕竟网盘链接的分发不如对象存储稳定。

4.4 三条路线的选择对比

简单总结：仓库内要追踪历史的用LFS，对外分发的用Release，超过2GB的才考虑外部存储。这个选择逻辑弄清楚了，后面就不会纠结了。

5. 大文件进仓库之后的连锁反应：仓库体积、克隆速度、配额

上一节讲的是怎么处理大文件，这一节聊聊为什么不能把大文件随意往仓库里丢。很多人觉得“我项目小，放一个100MB的文件应该没事吧”，其实问题比想象的严重。

5.1 仓库体积失控的后果

Git的设计初衷是管理文本代码，它对文本文件的压缩效率很高，但对二进制文件几乎无能为力。一个100MB的模型文件进了Git历史，哪怕后来的提交把它删了，这个100MB依然会永久留存在.git目录里。仓库的历史越长，这种“毒瘤”文件积累得越多，仓库体积会远超你的预期。

后果是什么呢？第一，任何人克隆这个仓库，都要把所有历史版本下载下来。假设你的仓库历史里有5个版本都包含一个100MB的文件，那克隆时就要下载500MB。第二，GitHub网页端的仓库页面会变得卡顿，文件浏览直观感受很差，代码评审也不方便。第三，如果你用的是免费账户，仓库内有大量二进制文件，可能会触发GitHub的滥用检测。

5.2 该不该把生成物进仓库

我个人的原则是：凡是可以重新生成的，都不进仓库。模型权重可以从训练脚本重新训练得到，前端压缩包可以重新打包，这些都属于“生成物”，放进Release或外部存储即可。只有源代码、配置、文档、自动化脚本这种“原材料”，才是仓库应该管理的东西。

为此，项目根目录一定要配好.gitignore文件。如果你3分钟前还在为生成物纠结，现在请放下，先写一个干净的.gitignore。以Python项目为例，至少要忽略这些：

__pycache__/ *.pyc dist/ build/ *.egg-info/ .venv/

前端项目则要忽略：

node_modules/ dist/ *.log

.gitignore的规则很直观，每一行是一个匹配模式，支持通配符。它的作用是让Git自动忽略你不想跟踪的文件。如果你是大文件问题的受害者，极大概率是.gitignore没配好。更重要的是，.gitignore本身要提交到仓库，让大家共用同一套忽略规则，避免各人本地状态不一致。

6. 上传过程遇到报错和页面打不开时的排查链路

在帮别人解决GitHub问题的过程中，我总结了一套自己的排查思路。GitHub的使用中，报错和访问不了是两个最让人头疼的拦路虎，但只要掌握链路，大部分都能自己搞定。

6.1 页面打不开的常规排查顺序

先说“github打不开”这个问题，这个普遍存在。GitHub作为一个境外网站，访问不稳定是常态，而且打不开的原因可能出在好几层，不要一上来就怪网络，按顺序排查：

第一层：确认浏览器和DNS缓存。有时候是无痕窗口打开不了，有时候是本地DNS缓存脏了。在命令行执行ipconfig/flushdns（Windows）或sudo dscacheutil -flushcache（macOS）清一下DNS缓存，刷新几次浏览器再看。

第二层：换一个网络环境。把WiFi切到手机热点，或者从家里网络切到公共网络，看看能不能打开。能打开说明你原来的网络环境有问题，换回原来的网络后再进一步处理。

第三层：检查本地hosts文件。GitHub的域名解析偶尔会被污染，手动在hosts文件里指定GitHub的IP，有时候能解决。但注意，IP地址会变动，这个方法治标不治本，只适合临时应急。

第四层：如果以上都不行，而且你已经配置了代理环境变量，检查一下系统代理设置是否正常。有时某些软件会修改系统网络设置，导致GitHub被错误地路由。

注意：无论遇到什么情况，都不要去下载那些宣称能“加速GitHub访问”的第三方工具。这类工具普遍存在安全隐患，有些会窃取你的GitHub账号凭据，或者在你电脑里植入其他软件。通过调整系统配置解决不了的问题，请使用官方文档和正规方式。

6.2 常见push报错信息对照

Push失败是出现频次最高的报错场景。我把常见的几种整理成了一个对照表：

报错信息本身就告诉了你原因，很多新手被吓住了，其实读一下英文就懂了。比如repository not found，除了仓库不存在，还有一种常见情况是URL里的用户名大小写写错了，或者仓库是私有的而你的账号没有被授权。Authentication failed则大概率是token问题，GitHub在2021年8月之后彻底关闭了密码推送，你必须用token代替密码。

6.3 一个值得养成的操作习惯：commit之前先check

报错大多数由信息不同步引起。你本地写了一天代码，远程仓库已经被别人推了好几次提交，你直接push肯定会冲突。养成一个好习惯可以大幅降低这种问题：每次提交之前，先git pull再git push。

更稳妥的顺序是：

git status # 查看当前状态 git add . # 添加到暂存区 git commit -m "说明" # 本地提交 git pull --rebase origin main # 拉取远程并变基 git push origin main # 推送

--rebase参数的作用是把你的本地提交接到远程最新提交的后面，让历史保持线性，而不是生成一个多余的合并提交。这样做的好处是，万一出现冲突，你能在自己的环境里先解决完，再推送一个干净的版本。

7. 让代码仓库更受欢迎：项目说明与维护习惯

代码上传只是第一步，一个能被别人看懂、愿意star的仓库，还需要花心思维护。很多人在GitHub上分享完代码就再也不管了，过几个月连自己都看不懂当初的逻辑，这是非常亏的。

7.1 README怎么写才能让访客一眼看懂

README是仓库的门面，也是访客第一个看到的内容。写得好的README，应该能在30秒内告诉别人：这个项目是做什么的，怎么安装，怎么使用。我常用的结构是：

• 项目名称和一句话简介
• 功能特性列表
• 环境要求
• 安装步骤
• 使用示例
• 目录结构说明
• 许可证和作者信息

如果项目里用了大文件，还要在README里写明大文件放在哪里、怎么下载、放在项目的什么位置。比如：“模型权重请从Release页面下载，解压后放到./weights/目录下。”这句话可以避免大量新手克隆仓库后发现代码跑不起来，然后在Issue区刷屏问原因。

7.2 版本记录与分支管理的实用建议

维护一个开源仓库和个人项目，建议从一开始就养成两件事：打Tag和写CHANGELOG。每次发布一个稳定版本，就用git tag -a v1.0.0 -m "release description"打一个版本标签，推到远程：git push origin v1.0.0。Tag是Release的基础，GitHub会自动把Tag关联到Release，访客可以清晰看到每个版本的变化。

如果项目稍微正规一点，建议用分支管理。main分支保持稳定，新功能在dev分支上开发，测试通过后再合并回main。这个流程对企业协作是刚需，对个人项目也能降低风险——至少你不会把“写了一半的代码”直接暴露给访客。

CHANGELOG可以有更轻松的形式：每次更新后在README末尾追加一段“更新记录”，写清楚版本号、日期和变更内容。这种做法成本极低，但对维护者自己的价值极高。我翻自己三个月前写的仓库，全靠CHANGELOG才能快速回忆当初做了哪些决定。

8. 我的经验总结：三个核心认知

写到这里，大部分操作细节都覆盖到了。最后分享三个我用了很久的核心认知，它们比任何具体命令都重要。

第一，GitHub仓库的核心价值是版本历史。网页上传虽然方便，但丢失了版本管理的灵魂。凡是认真维护的项目，请务必用Git命令行的方式操作，哪怕初期学习成本高一点。

第二，大文件问题的本质是选错存储位置。Git不是不能放大文件，而是要根据用途选择LFS、Release还是外部存储。这个选择的判断标准非常简单：这个文件要不要跟着代码版本走？要就用LFS，不要就放Release。

第三，遇到问题先读报错信息，再动手搜索。GitHub的报错信息非常明确，答案基本都在里面。养成读报错的习惯，比收藏100条教程都有用。关于“打不开”的问题，按网络排查链路一步步来，先清缓存、再换网络、最后考虑系统配置层面，不要一上来就乱下载工具，安全永远是第一位的。

我现在每次开新仓库，第一件事不是写代码，而是先把.gitignore和README写明白。这个习惯我保持了很多年，它让我所有公开项目都能随时捡起来继续做，也让每个来到仓库的人都能顺利上手。希望这篇文章也能帮你少踩几个上传路上的坑。