GitHub新手入门全指南：仓库、提交、推送与Pages部署

第一次接触GitHub的人，通常不是在学它，而是在“被它卡住”：想找个开源工具，看到一堆英文按钮不知道点什么；照着网上的命令敲了半天，结果本地文件没推上去，还冒出一堆红色报错。这篇GitHub入门笔记，是我带新人做毕设、帮同事跑开源项目时反复讲过的一套内容，包含注册、建仓库、传代码、跑项目、提PR、部署个人页面，全程用大白话，不给术语加滤镜。我不打算让你背命令，而是帮你把每一步背后的逻辑理清楚，照着做，一个小时内完成第一次提交是没问题的，而且以后再看任何GitHub仓库，你都敢点进去。

1. 入门前，先把五个核心概念在脑子里过一遍

1.1 GitHub 是代码托管平台，不是编程语言

很多新手最容易混淆的就是Git和GitHub。Git是一个版本控制工具，负责记录文件每次改动的细节，谁改了、改了哪一行、什么时候改的，它都记得；GitHub则是基于Git的在线托管平台，相当于给代码找了个既能备份、又能协作的“网盘+工单系统”。GitHub本身不教你写代码，它是存放代码、展示代码、协作代码的地方。

你在这个平台看到的每一个项目，都叫“仓库”。仓库可以公开也可以私有，公开仓库任何人都能克隆一份到本地，甚至帮你改代码、再提交回作者那里。理解这一点之后，再看那些花里胡哨的界面就不会懵了——你只需要关心三件事：账号、仓库、提交记录。

为什么建议先搞懂概念再碰命令？因为Git命令本身并不难，难的是你不知道每一步操作到底在改什么。很多人在终端里输入git add .，却不理解这个点是“把当前目录全部改动加入暂存区”，后面出问题时自然不知道怎么处理。概念建立起来，命令只是对应动作的快捷键。

1.2 仓库、提交、分支、远端怎么对应实际操作

把这四个词塞进日常场景里，就很好理解：

• 仓库：一个文件夹，通常包含项目代码、文档、配置文件。
• 提交：对文件当前状态拍一张快照，附带一句说明，方便以后回溯。
• 分支：平行世界。你在自己的分支里随便改，不影响主分支上的稳定代码。
• 远端：云端仓库地址，也就是GitHub上那个仓库。

实际工作流就是：你在本地改代码，然后把改动打包成提交，再推送（push）到远端；别人更新了代码，你拉取（pull）下来。一次协作循环无非是这四步，明白这一点，后面所有操作都是在这四步上做变体。

举个生活化的例子：提交像是你在文档里存草稿，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 Desktop

Windows用户直接去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是把当前分支命名为main；git 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 LFS（Large 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 dev

Python项目则是这样：

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、Issue

5.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 Pages

Hexo是目前比较流行的静态博客框架，把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 deploy

hexo 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了。希望这篇入门笔记能让你的第一个提交顺利落地，少走点弯路。