第一次接触GitHub的人通常不是在学它而是在“被它卡住”想找个开源工具看到一堆英文按钮不知道点什么照着网上的命令敲了半天结果本地文件没推上去还冒出一堆红色报错。这篇GitHub入门笔记是我带新人做毕设、帮同事跑开源项目时反复讲过的一套内容包含注册、建仓库、传代码、跑项目、提PR、部署个人页面全程用大白话不给术语加滤镜。我不打算让你背命令而是帮你把每一步背后的逻辑理清楚照着做一个小时内完成第一次提交是没问题的而且以后再看任何GitHub仓库你都敢点进去。1. 入门前先把五个核心概念在脑子里过一遍1.1 GitHub 是代码托管平台不是编程语言很多新手最容易混淆的就是Git和GitHub。Git是一个版本控制工具负责记录文件每次改动的细节谁改了、改了哪一行、什么时候改的它都记得GitHub则是基于Git的在线托管平台相当于给代码找了个既能备份、又能协作的“网盘工单系统”。GitHub本身不教你写代码它是存放代码、展示代码、协作代码的地方。你在这个平台看到的每一个项目都叫“仓库”。仓库可以公开也可以私有公开仓库任何人都能克隆一份到本地甚至帮你改代码、再提交回作者那里。理解这一点之后再看那些花里胡哨的界面就不会懵了——你只需要关心三件事账号、仓库、提交记录。为什么建议先搞懂概念再碰命令因为Git命令本身并不难难的是你不知道每一步操作到底在改什么。很多人在终端里输入git add .却不理解这个点是“把当前目录全部改动加入暂存区”后面出问题时自然不知道怎么处理。概念建立起来命令只是对应动作的快捷键。1.2 仓库、提交、分支、远端怎么对应实际操作把这四个词塞进日常场景里就很好理解仓库一个文件夹通常包含项目代码、文档、配置文件。提交对文件当前状态拍一张快照附带一句说明方便以后回溯。分支平行世界。你在自己的分支里随便改不影响主分支上的稳定代码。远端云端仓库地址也就是GitHub上那个仓库。实际工作流就是你在本地改代码然后把改动打包成提交再推送push到远端别人更新了代码你拉取pull下来。一次协作循环无非是这四步明白这一点后面所有操作都是在这四步上做变体。动作本地还是远端作用commit本地为当前改动记录一个版本快照push本地→远端把本地提交上传到GitHubpull远端→本地把远端最新改动下载下来clone远端→本地把整个仓库完整复制到本地举个生活化的例子提交像是你在文档里存草稿push相当于把草稿发到共享网盘pull相当于把同事改过的版本同步回来。把“分支”想成草稿的不同版本就很好理解为什么要先建分支再改代码。1.3 命令行和 GitHub Desktop新手选哪个我的建议分两种情况如果你想把原理学透、后续要参与开源项目或从事开发工作命令行是绕不开的至少要会基础的add、commit、push、pull如果你只是想把手里的作业、项目文件传到GitHub上或者不喜欢和终端打交道那就直接从GitHub Desktop开始。GitHub Desktop是官方出的桌面客户端把add、commit、push三个过程拆成了三个明确的按钮每一步出错都会给出红色提示。我见过很多初学者一句话卡在命令行半小时换到桌面端两分钟就摸清楚了。不是命令行不好而是新手在概念没建立之前命令行的反馈太抽象容易挫伤积极性。更实际的做法是先装GitHub Desktop完成第一次提交同时把常用命令抄下来对照着看。等你想清楚“提交、推送、拉取”分别对应什么再用命令行就很自然了。2. 注册账号和完成本地环境配置2.1 注册账号时注意用户名和邮箱这两个不能乱填注册GitHub账号时用户名会直接出现在你所有公开仓库的链接里比如https://github.com/你的用户名/仓库名。所以用户名尽量用简短、有识别度的英文不要起得过于随意因为以后求职、做开源贡献时这个链接就是你的技术名片。建议去Settings里把姓名、个人主页、简介都填上这会给访客留下专业印象。邮箱建议填常用邮箱。GitHub默认会按邮箱关联你的头像用的Gravatar服务别人看到你的提交记录时点开头像能看到联系邮箱。如果你不希望暴露真实邮箱GitHub也提供了users.noreply.github.com这种隐私邮箱可以在Settings里开启。开启之后本地Git配置用这个隐私邮箱提交记录就不会泄露真实邮箱。注册完成之后我建议立刻开启两步验证。密码加动态验证码比单一密码安全得多后面还要配置令牌、密钥这一步不做的话账号风险会高很多。2.2 安装 Git、登录 GitHub DesktopWindows用户直接去Git官网下载安装包一直下一步就行macOS用户装好Xcode Command Line Tools后自带Git。装完后在终端输入git --version能看到版本号就说明装好了。接着安装GitHub Desktop安装完用浏览器登录你的账号它会自动帮你完成初始配置。桌面端有个很方便的功能打开任意一个文件夹选择“Create new repository”就能把一个普通文件夹变成Git仓库。这对命令行还不熟的新手来说几乎是零成本上手。这里强调一点桌面端登录后会保存账号凭证后续pull、push一般不会再频繁要求输入密码。如果你更习惯命令行GitHub官方还推出了gh命令行工具登录一次就可以管理仓库、提PR、发布Release比手写HTTPS认证省事很多新手也可以直接用它起步。2.3 配置 SSH 密钥还是直接用 HTTPS连接远端仓库有两种方式HTTPS和SSH。HTTP方式每次操作可能要求输入账号密码或令牌SSH方式则用密钥配对配置一次之后长期免密更省心。我建议有精力就两步都搞定。生成SSH密钥的命令ssh-keygen -t ed25519 -C 你的邮箱一路回车会生成一对密钥默认放在~/.ssh/目录下id_ed25519.pub是公钥、id_ed25519是私钥。然后终端执行cat ~/.ssh/id_ed25519.pub把输出的内容整段复制粘贴到GitHub的Settings → SSH and GPG keys → New SSH key里标题随意保存即可。之后在终端里执行git config --global user.name 你的用户名和git config --global user.email 你的邮箱本地身份就算配好了。HTTPS方式则需要生成个人访问令牌PAT。在Settings → Developer settings → Personal access tokens里生成注意只勾选你需要的权限比如仓库读写就勾Contents权限不要图省事全选。这个令牌只显示一次务必复制保存好。3. 把文件夹传上 GitHub三种方式任选3.1 网页端直接上传适合文件数量少的场景如果你只有一个临时写好的文档、一个配置了半天的脚本不想装任何工具可以直接用网页端上传。进入你的仓库页面点击Add file → Upload files把文件拖进去填写提交说明点Commit changes就完成了一次提交。整个过程非常直观适合演示或一次性上传。但网页端有两个明显限制一是单次上传文件有数量和大小的限制文件多、体积大时会失败二是它无法处理持续更新你每改一个文件都要重新上传过程极其繁琐。所以网页端只推荐用于临时小文件存放真正要维护的项目还是建议走下面两种方式。3.2 用 GitHub Desktop 拖拽上传文件夹桌面端传文件夹是我最推荐新手使用的方式。先点击File → Add Local Repository选择你已经写好代码的那个文件夹如果它还不是Git仓库桌面端会提示你创建点一下Create repository就搞定。然后你会看到桌面端界面左边列出一堆改动文件这就是Git的暂存区概念——它把所有改动先收集起来等你想好再提交。在左下角填上Summary提交说明比如“first commit”点Commit to main再点Push origin文件就上传到GitHub了。如果你还没有在GitHub上建仓库也可以直接点Publish repository它会让你选择仓库是公开还是私有填好仓库名就能一键完成远端创建和推送。这种“先在本地准备再从桌面端绑定远端”的路径比网页端建空仓库再关联要顺畅得多我实际操作时更喜欢这个顺序。3.3 命令行方式git init/add/commit/push 完整流程命令行是绕不开的建议至少跟着敲一遍。假设你有一个my_project文件夹里面是待上传的代码cd my_project git init git add . git commit -m first commit git branch -M main git remote add origin https://github.com/你的用户名/你的仓库名.git git push -u origin main一句一句解释git init是把这个文件夹变成Git仓库git add .是把当前目录所有改动加入暂存区点号代表当前目录git commit是提交并附上说明git branch -M main是把当前分支命名为maingit remote add origin是绑定远端地址最后git push -u origin main就是把本地main分支推送到远端顺便建立关联以后可以直接用git push。注意git remote add origin这行里的仓库地址必须先到GitHub上新建一个空仓库才有效否则会报Repository not found。新建仓库时不要勾选“Initialize this repository with a README”因为空仓库才能和本地历史合并你如果选了还要处理大量冲突对新手不友好。3.4 .gitignore 和大文件处理很多人栽在这两步上传之前一定要建一个.gitignore文件把你不需要提交的内容排除在外。常见的需要排除的是node_modules依赖目录、.env环境变量文件、编译生成的文件、IDE配置目录。原因是这些内容往往体积巨大或包含敏感信息提交到GitHub上会拖慢仓库甚至泄露密钥。.gitignore最简单的内容可以这样写node_modules/ .env .DS_Store dist/再说大文件。GitHub对单个文件有100MB的硬限制超过100MB会直接拒绝push仓库整体建议保持在1GB以内。如果你的项目里有模型文件、数据集或者压缩包这种大文件不要硬塞进仓库Git官方给出的方案是Git LFSLarge File Storage需要额外安装跟踪器对新手来说步骤不少。更务实的做法是把大文件放到网盘或对象存储里代码中只保留下载链接。我见过很多新人对着一台报错“文件过大”的终端干瞪眼其实问题根源不是Git不会用而是设计仓库时没想清楚哪些东西该进版本控制哪些不该进。4. 拿到一个项目后我该怎么跑起来4.1 先在仓库首页做一次“项目体检”很多人拿到一个GitHub项目第一件事就是把代码下载下来然后试图编译运行结果频繁失败。其实在克隆之前花三分钟做一次“项目体检”能避开大部分坑。看仓库首页这五个信息就够了README文件讲没讲清楚这个项目怎么装、怎么用最近有没有活跃的提交记录判断项目是活着还是停更了Star数和Fork数简单热度参照License是什么类型决定你能不能商用、怎么署名Issues区有没有大量未处理的报错帮你判断项目维护状态。以我自己的经验来说一个新项目如果README特别简略、最近一次提交在半年前、Issues里全是求助没人回那即使Star过千我也会先观望。选择活跃维护的项目你的使用体验会完全不一样遇到问题至少有地方问。4.2 按 README 的正确姿势安装依赖和运行拿到好的项目在本地跑起来通常是有套路的。先找到README里“Installation”或“Getting Started”这一段然后按它来。拿一个Node.js项目举例通常是这样git clone https://github.com/用户名/仓库名.git cd 仓库名 npm install npm run devPython项目则是这样git clone https://github.com/用户名/仓库名.git cd 仓库名 pip install -r requirements.txt python main.py我的建议是不要跳过“检查版本”这一步。在安装依赖前先执行node -v、python --version确认版本范围不少项目对版本有硬性要求。很多报错根本不是代码问题而是Python版本不对、Node版本太老。你如果依赖管理工具用的是conda或uv逻辑也是相同的先锁定语言版本再装依赖最后执行入口文件。如果项目提供了Docker方式那更适合新手因为环境已经封装好了执行docker compose up就完事了不污染你本机的环境。判断项目是否支持Docker看仓库根目录有没有Dockerfile或docker-compose.yml即可。4.3 Release 页面只想用成品就直接来下载不是所有项目都要求你从源码编译。很多成熟项目会打发布包你把页面切到Release标签就能看到一个个版本列表最新版在最上面。Release页面里通常有编译好的可执行文件、压缩包或安装脚本下载下来直接用对非开发者用户非常友好。注意一个细节Release页面里的“Source code (zip)”和编译好的二进制包不是一回事。源码包只是代码快照和你在Clone里拿到的内容一致仍然需要编译环境才能运行而带操作系统名或扩展名的文件比如.exe、.dmg、.AppImage才是可以直接运行的成品。下载前看一下文件类型看不懂就回到README找“Download”或“Installation”段落。4.4 GitHub Actions 显示的小图标是状态不是装饰很多新手看README顶部那一排彩色小徽章以为纯粹是装饰其实那些是项目的持续集成状态图标。比如写着“build passing”绿色徽章就说明上次自动化构建是成功的红色则代表失败。徽章背后是GitHub Actions简单理解就是云端自动化流水线每次有人提交代码它会在GitHub的服务器上自动做编译、测试、打包。点击这个徽章或进入仓库的Actions标签页你能看到每次提交对应的构建日志。这个方法很有用如果项目已经构建失败很久了那说明它可能处于不稳定的开发状态直接使用要谨慎。我建议你也学着给自己的项目加上一个简单的Actions配置理由很实际很多同学做完课设或开源项目最怕的就是别人克隆下来跑不起来。如果你在仓库里放一个自动构建脚本别人看到徽章是绿色就能快速确定这个项目在我当前状态下是能通过的你的项目信任度会明显上升。5. 学会参与上游项目Fork、PR、Issue5.1 用 Fork 创建属于自己的副本Fork是GitHub上非常核心的协作动作但很多新手误以为它只是“复制按钮”。Fork的准确含义是把别人的仓库复制一份到你自己的账号下形成一个独立的副本你在这个副本里可以随意修改、试验不会影响原项目也不会需要原作者的授权。Fork之后你的账号下就有了一个同名仓库但它和原仓库之间还保留着关联关系。你可以在Settings里看到这个仓库是forked from原仓库以后原仓库更新时你能通过“Sync fork”按钮把原仓库的最新内容同步过来。这个特性对参与开源社区非常关键。为什么要用Fork而不是直接Clone一份因为Clone来的仓库没有原远端的关系你改完之后根本无法在原仓库页面发起改动申请而Fork后的副本天然支持向原始仓库发起Pull Request这是开源协作的基础链路。5.2 提交 Pull Request 的完整链路Pull Request简称PR是“请求对方把你的改动合并进他的代码库”的意思它是开源协作的核心流程。完整的操作链路是Fork → Clone → 新建分支 → 改代码 → 提交 → Push到你的Fork → 在原仓库页面发起PR。用命令行走一遍git clone https://github.com/你的用户名/原仓库名.git cd 原仓库名 git checkout -b feature/my-change # 改你的代码 git add . git commit -m 描述你的改动 git push origin feature/my-change推送完成后回到原仓库页面GitHub会高亮显示一个“Compare pull request”按钮点击后写清楚你改了什么、为什么改就可以提交了。原仓库维护者看到后会Review你的代码可能直接合并也可能留言要求修改。有几个实操细节特别重要第一动手改代码前先看仓库有没有CONTRIBUTING.md文件很多项目会把提交规范写在里面第二如果提交前上游仓库已经更新一定要先同步方法是在Fork仓库页面上点“Sync fork”第三PR描述一定要具体维护者没有义务通过你的代码阅读来猜你的意图描述写不清很容易被关掉。5.3 提 Issue 前先搜再看避免被维护者关闭Issue是GitHub上的“工单系统”用来提交bug、功能建议、技术讨论。但新手在Issue区最容易犯的错误是问一些文档里已经写清楚的问题或者重复提交别人已经报过的bug。这样不仅得不到帮助还会被维护者标记为“duplicate”然后关闭。正确姿势是先做三件小事第一用Isues搜索框搜一遍你的关键词看看有没有已经存在的同类问题第二看README和文档里是否有相关内容第三如果项目有Discussions版块简单的使用问题一般更适合放到那里面问而不是直接提Issue。提Issue时模板很重要。一个好的bug报告应该包含复现步骤、期望结果、实际结果、环境信息操作系统、版本号、尽量附上日志或截图。你提供的信息越完整维护者越容易定位问题解决的效率也就越高。6. 部署个人页面GitHub Pages 与 Hexo 组合6.1 最简单的 Pages 部署GitHub Pages是GitHub提供的免费静态网页托管服务适合个人主页、项目文档、博客。最简部署流程不写一行代码就可以实现新建一个仓库仓库名必须叫用户名.github.io然后进入Settings → Pages在Build and deployment里选择Deploy from a branch分支选main、路径选/root保存之后等一分钟访问https://用户名.github.io就能看到页面了。如果你是自己维护文档我建议在仓库里放一个简单的index.html过一遍部署流程然后再用专业工具。第一次部署成功的成就感非常关键后续折腾Hexo、VuePress时你会有基础。重要提示GitHub Pages发布后有缓存延迟推完代码不一定立即更新不用反复刷新。进入Actions标签页等构建完成的绿色对勾出现再刷新页面基本就能看到最新内容了。6.2 把 Hexo 博客部署到 GitHub PagesHexo是目前比较流行的静态博客框架把Hexo部署到GitHub Pages是很多人的第一个博客项目。整个过程分两部分本地生成静态文件、推送到Pages仓库。先安装环境npm install -g hexo-cli hexo init blog cd blog npm install然后安装部署所需的插件npm install hexo-deployer-git --save编辑根目录下的_config.yml在末尾配置部署信息deploy: type: git repo: https://github.com/你的用户名/你的用户名.github.io.git branch: main之后每次更新博客执行三连hexo clean hexo generate hexo deployhexo generate负责生成静态文件到public目录hexo deploy负责把public目录推送上去。比较需要注意的坑是_config.yml里的url字段要改成你的主页地址否则站内链接和站点地图会指向错误还有别在public目录里手动改东西因为每次生成都会清空重来。6.3 部署踩坑记录分支选择、缓存和资源路径用Hexo部署时最常踩的三个坑我都碰到过。第一个坑是部署分支搞错GitHub Pages现在默认用main分支但老教程里会写master照着旧教程做会部署失败。部署前先确认你仓库的默认分支名通常新仓库是main老仓库可能还是master。第二个坑是强制推送问题。Hexo默认部署时会强制覆盖远端分支如果你还把源码也放在同一个仓库里强制推送可能把源码也弄丢。我的做法是分成两个仓库源码放一个私有仓库生成后的静态文件放用户名.github.io仓库两个仓库互不干扰。第三个坑是静态资源路径。如果部署后页面样式丢失先检查_config.yml里有没有设置root路径。GitHub Pages的子路径部署有常见错误主页部署则很少出问题。7. 常见问题速查认证、冲突、误删文件怎么处理7.1 Authentication failed 和 403 的原因与对策报错fatal: Authentication failed是新手遇到最多的认证问题。最常见的原因是你虽然安装了Git但没有配置本地身份信息或者HTTPS方式要求输入的不是密码而是PAT个人访问令牌。GitHub从2021年8月起就关闭了密码方式push坚持输入账号密码自然会失败。解决办法是如果还没有生成PAT按前面章节的方法创建一个更省事的办法是安装gh命令行工具执行gh auth login它会引导你完成浏览器授权自动处理令牌的生成和存储。对于403报错多半是令牌权限不够或者账号没有足够的权限访问该私有仓库去检查令牌设置和仓库权限即可。7.2 合并冲突看到 别慌合并冲突几乎是每个人都会遇到的。当本地文件和远端文件在同一位置做了不同修改时Git无法自动判断该保留哪个就会在文件里插入冲突标记把选择权交给你。打开冲突文件你会看到类似这样的标记 HEAD 你的本地改动 远端的改动 origin/main解决办法是逐个处理保留你想保留的部分删掉、、这三行标记保存文件然后执行git add 文件名再git commit完成合并。整个过程就是手动把矛盾解决掉重新提交一次。很多新手不知道的是合并冲突并不可怕可怕的是在冲突状态里继续操作。你应该先看git status把冲突文件列表整理清楚逐个解决再继续下一步。7.3 Copilot 和学生认证被拒是怎么回事GitHub Copilot是GitHub提供的编程助手可以按上下文自动补全代码很多学生和教师可以使用免费认证。被拒的常见原因是申请时填写的邮箱和你GitHub账号绑定的邮箱不一致学校邮箱域名不在官方支持列表或者账号注册时间太短、没有活跃的提交记录导致系统判定你不是真实活跃的用户。解决思路是先去Settings里确认主邮箱是教育邮箱再检查教育认证页面是否显示“Active”状态。如果申请被拒按页面提示补充材料重新提交一般在几个工作日内会得到结果。要注意的是教育认证福利只针对本人不要用别人的账号代认证或共享账号账号安全永远比免费额度重要。7.4 误提交敏感信息和大文件的补救办法如果不小心把.env文件、密钥或大文件推上了GitHub首要任务不是删除文件而是先撤销泄露。密钥类信息必须立刻到服务商那边吊销并重新生成因为一旦推送到远端任何看到仓库的人都可能已经复制了它只改本地文件根本来不及。之后再用git rm --cached 文件名把文件从Git追踪中移除同时更新.gitignore防止再次提交。如果你还需要清理提交历史可以用git filter-repo工具但这个操作会改写历史必须仔细评估后再执行而且对已经Fork过仓库的项目来说历史清理意义不大。我建议防患于未然在仓库里放一个检查用的脚本在提交前扫描有没有包含password、secret、api_key等敏感关键词的关键文件能省去很多麻烦。8. 最后分享几个我自己长期使用的GitHub习惯这篇文章写到这该给的建议基本都给到了最后聊点我自己的体会。第一我带过很多零基础的同学他们最容易卡住的不是命令本身而是不知道每一步在干嘛。所以我建议你动手时在旁边开一个浏览器把一个仓库的Issues、Commits、Actions页面都点一遍看每个动作对仓库产生了什么影响。代码提交上去之后回到网页端刷新看到文件躺在列表里的那一刻你会发现原来GitLab、Gitee这类平台的操作逻辑都差不多。第二如果你觉得某个仓库历史乱成了一锅粥不要急着删除重建。先执行git log --oneline看看提交记录大概长什么样再用git status确认当前状态很多时候只是分支命名混乱或提交顺序问题用git rebase重新整理一下就行比删库重来快得多也更能锻炼你的理解。第三GitHub最好的学习材料就是社区项目本身。去找一个你每天都用的小工具把它的代码读一遍哪怕只读懂一个模块也比刷十篇教程有收获。你的目标是让一个项目的运行逻辑在你脑子里变得透明到了这一步你就真正掌握GitHub了。希望这篇入门笔记能让你的第一个提交顺利落地少走点弯路。