GitHub新手入门：从注册到推送第一个仓库

GitHub 上的第一个小时会带来什么

在 GitHub 上的第一个小时结束时，您将拥有 4 样东西：一个可以使用多年的账户、一个存放真实项目的仓库、一份说明项目用途的 README，以及从您自己的计算机成功推送的内容。GitHub 是用于托管 git 仓库的服务，并围绕仓库提供代码审查和自动化工具。它会保存您的代码及其每个版本，也可以托管静态网站。但它不会运行您的程序。

初学者最容易在最后一点上浪费时间，因此有必要一开始就说明。本文其余部分按顺序介绍这 1 个小时，并包含过程中会遇到的错误消息。如果您希望先了解定义，请先了解 GitHub 是什么；如果这些名称仍然容易混淆，请阅读git、GitHub 和 git 服务器是 3 个不同的概念。

第 0 到 10 分钟：账户和用户名

在 github.com 注册。表单很简短。唯一值得认真考虑的是用户名。

用户名会成为你分享的每个地址的一部分，github.com/yourname/project，也会出现在其他人针对你的项目运行的每条克隆命令中。选择一个你愿意写在求职申请上的名称。使用小写字母，简短易读，不要包含出生年份。之后可以重命名，GitHub 也会将指向旧仓库的链接重定向，但指向旧个人资料页的链接会返回 404，释放出的用户名还可能被其他人抢先注册。现在选好可以避免这些问题。

GitHub 要求参与代码贡献的账户启用双因素身份验证（2FA，即密码之后的第二个登录步骤），因此会要求你完成注册。请在手机上使用身份验证器应用，并将恢复代码存放在手机以外的位置。如果手机和恢复代码同时丢失，账户恢复过程会很慢，而且通常无法完成，因为 GitHub 无法证明该账户属于你。

请使用一个你在三年后仍会查看的电子邮件地址注册。之后可以添加学校邮箱作为辅助邮箱。这一点很重要，因为 GitHub Student Developer Pack 由 GitHub Education 在核实你仍是注册学生后授予。应将它视为需要申请并确认资格的权益，而不是默认已经拥有的权益。截至 2026 年 8 月，免费计划已经包含无限量的公共和私有仓库，因此本指南的任何内容都不依赖该申请是否获批。

第 10 到 20 分钟：创建您的第一个仓库

仓库通常简称为 repo，包含一个项目的文件，以及对这些文件所做每次更改的完整历史记录。单击页面右上角的加号图标，然后选择 New repository。

1. 使用项目名称命名，全部使用小写字母，并用连字符分隔。该名称会成为 URL。
2. 编写一行描述。它会显示在搜索结果和您的个人资料中。
3. 选择 Public 或 Private。Public 仓库中的内容任何人都可以读取。Private 仓库中的内容只有您和受邀人员可以读取。
4. 勾选“Add a README file”。这会创建第一次提交，因此仓库不会为空。
5. 为您的语言选择一个 .gitignore 模板。它会将 node_modules、.env 文件和构建输出排除在历史记录之外。
6. 如果代码是公开的，请添加许可证。没有许可证，其他人就没有合法权限复用代码。

.gitignore 的选择比看起来更加重要。机密信息一旦推送到公共仓库，从那一刻起就是公开的。即使在后续提交中删除文件，也不会将其从历史记录中删除，因此任何人仍然可以读取它。自动扫描器会在推送后的几分钟内发现已提交的 API 密钥。如果发生这种情况，请先轮换密钥，再清理历史记录。

安装 Git 并设置身份信息

sudo apt update && sudo apt install -y git
git --version
git config --global user.name "Your Name"
git config --global user.email "you@example.com"

git --version 应输出类似 git version 2.43.0 的一行。Ubuntu 24.04 和 Debian 13 都自带较新的 Git。在 Windows 或 macOS 上，应改为从 git-scm.com 安装；其中两行 git config 命令在所有系统上的写法都相同。

git config 中的电子邮件地址不是登录凭据，而是写入您创建的每个提交中的标识。GitHub 会将该标识与您账户中的地址进行匹配，从而将提交关联到您的个人资料。请将其设置为 GitHub 已知的地址，否则提交中虽然会显示您的姓名，但不会关联到任何账户，也不会显示在贡献图中。如果您不希望公开个人地址，GitHub 会为每个账户提供一个格式类似 12345678+yourname@users.noreply.github.com 的 no-reply 地址，该地址列在电子邮件设置页面中。请在此处使用该地址。

第20到35分钟：密码无法使用，因此配置密钥

Git 通过 HTTPS 或 SSH 访问 GitHub。SSH 是安全 shell，也是一种加密协议，您还会使用它连接服务器，详见SSH 是什么以及基于密钥的登录如何工作。您的账户密码在这两种方式下都不再接受。通过 HTTPS 使用密码推送时，会出现以下错误：

remote: Support for password authentication was removed on August 13, 2021.
fatal: Authentication failed for 'https://github.com/yourname/my-first-site.git'

通过 HTTPS 时，应改用个人访问令牌。您可以在 Settings、Developer settings 中创建令牌，并在输入密码的位置输入它。通过 SSH 时，应改用密钥对。之后几年使用时，需要输入的内容更少。创建密钥对：

ssh-keygen -t ed25519 -C "you@example.com"
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
cat ~/.ssh/id_ed25519.pub

按 Enter 接受默认文件路径。是否设置口令短语由您决定，但建议设置，因为任何复制私钥文件的人都可以冒充您进行推送，直到您从账户中删除该密钥。

ssh-keygen 会写入两个文件。~/.ssh/id_ed25519 是私钥，永远不要离开此计算机。~/.ssh/id_ed25519.pub 是公钥部分，刚才由 cat 输出。复制整行内容，从 ssh-ed25519 开始，然后在 GitHub 的 Settings、SSH and GPG keys、New SSH key 中粘贴。

在需要使用前先测试：

ssh -T git@github.com

首次连接时，系统会要求您确认主机指纹。输入 yes。正常结果只有一行：

Hi yourname! You've successfully authenticated, but GitHub does not provide shell access.

这表示操作成功。GitHub 确实不提供 shell，该问候信息证明 GitHub 已接受您的密钥。Permission denied (publickey). 表示密钥未被接受，通常是因为粘贴的是私钥文件、只粘贴了公钥行的一部分，或将密钥添加到了其他账户。如果命令一直等待并最终超时，说明您的网络阻止了出站端口 22；大学和办公 Wi-Fi 经常如此。GitHub 也会在端口 443 上响应 SSH，因此 ssh -T -p 443 git@ssh.github.com 可以绕过大多数此类网络限制；将远程主机设置为 ssh.github.com 并使用端口 443 后，git 就会通过相同路径连接。

第 35 至 45 分钟：将本地工作放到 GitHub 上的 3 个命令

其中一些命令每个项目只需运行一次。另有 3 个命令会在以后每次修改时重复运行。请从存放代码的目录开始。

cd ~/projects/my-first-site
git init -b main
git add .
git commit -m "First commit"
git remote add origin git@github.com:yourname/my-first-site.git
git pull --rebase origin main
git push -u origin main

逐行说明：

• git init -b main 在当前目录创建隐藏的 .git 目录，并在名为 main 的分支上开始记录历史。每个项目运行一次。
• git add . 将 .gitignore 未排除的所有文件加入暂存区。加入暂存区表示标记文件，使其包含在下一次提交中。
• git commit -m "First commit" 将暂存区中的文件保存为一个快照，并附加提交说明。
• git remote add origin git@github.com:... 将 GitHub 地址以短名称 origin 保存。每个项目运行一次。
• git pull --rebase origin main 获取 GitHub 为你创建的 README 提交，并将你的提交变基到该提交之上。
• git push -u origin main 将你的提交发送到 GitHub。-u 记录这组关联关系，因此之后推送时只需使用 git push。

之所以需要 pull --rebase 这一行，是因为你勾选了“添加 README 文件”，这表示 GitHub 中已经有一个提交，而你的计算机尚未获取它。如果远程仓库包含本地历史中没有的提交，Git 会拒绝推送，因为推送会丢弃这些提交。省略这一行会得到以下结果：

 ! [rejected]        main -> main (fetch first)
error: failed to push some refs to 'github.com:yourname/my-first-site.git'

如果本地目录中已经有自己的 README.md，变基会在该文件处因冲突停止。打开该文件，保留需要的文本，删除 <<<<<<< 标记行，然后依次运行 git add README.md 和 git rebase --continue。

检查结果：

git status
git log --oneline

git status 应显示 nothing to commit, working tree clean，并报告你的分支已与 origin/main 保持最新。git log --oneline 应列出你的提交和 README 提交。在浏览器中重新加载仓库页面，即可看到你的文件。

从现在开始，每次修改内容时都重复运行以下 3 个命令：

git add .
git commit -m "Describe what changed"
git push

有两个错误值得注意。在推送时出现 error: src refspec main does not match any，表示 main 上还不存在提交，因此 git commit 步骤失败或从未运行。明明修改过文件却出现 nothing to commit, working tree clean，表示你位于错误的目录，或者 .gitignore 正在排除这些文件；git status --ignored 会显示具体排除规则。

提交、分支和拉取请求是什么

提交是在某个时间点保存的整个项目快照，其中包含提交消息、作者和时间戳。它会一次涵盖所有受跟踪的文件，因此检出旧提交后，得到的是仍可运行的项目，而不是单独恢复的某个文件。

分支是指向某个提交的可移动名称。创建分支不需要额外成本，在分支上完成的工作不会影响 main，直到执行合并。main 是默认分支，也是访问者首先看到的版本。

拉取请求（PR）用于请求将一个分支合并到另一个分支。它会在同一页面汇总变更、讨论和自动检查结果。在团队中，代码审查就在该页面进行。在自己的仓库中，PR 不是必需的，但它会记录每项变更的原因。

git switch -c add-contact-page
git add .
git commit -m "Add contact page"
git push -u origin add-contact-page

推送命令会输出一个链接，邀请您为该分支创建拉取请求。打开链接，像审查其他人的代码一样检查自己的变更，然后执行合并。

README 和贡献图的用途

README 是项目的首页。GitHub 会将 README.md 直接显示在文件列表下方，因此它是访问者首先阅读的内容，而且对大多数仓库来说，也是他们唯一阅读的内容。README 中应写明以下 4 项内容：

• 用 1 句话说明项目的功能，不要使用术语。
• 说明如何运行项目，使用他人可以直接复制的命令。
• 说明运行前需要准备什么：语言版本、数据库、API 密钥。
• 说明项目当前所处的状态。“学习项目，不再维护”就是诚实且有用的表述。

再花 10 分钟准备一个个人 README 很值得。创建一个名称恰好是你的用户名的仓库，在其中放入 README.md，GitHub 就会将该文件显示在个人主页顶部。用一小段话说明你正在学习什么、构建过什么，提供的信息比一列半成品仓库更多。

招聘人员确实会查看这个个人主页，而且通常只会花不到 1 分钟。他们会打开个人主页，浏览固定的仓库，然后阅读其中一个 README 的开头。6 个能够在全新机器上分别启动、且各自拥有清晰 README 的小项目，比 1 个没人能运行的大项目更有说服力。

贡献图是个人主页上的方格网格。它统计提交、拉取请求、议题和评审。以下 2 条规则决定你的工作是否会显示出来。提交必须包含一个已关联到 GitHub 账户的电子邮件地址，因此前面的 git config user.email 步骤很重要。提交必须进入你拥有的仓库的默认分支，而不是进入复刻仓库。私有贡献会计入统计，但会隐藏；个人主页设置会将其显示为匿名方格。

不要为了管理贡献图而工作。每天提交一个只修改 1 个字符的提交，任何点击查看的人都能看到；与空白的一周相比，这种做法给人的观感更差。贡献图记录的是工作。它本身不是工作。

GitHub 不会为您运行的内容

GitHub 用于存储代码和运行短时任务。它不会托管持续运行的应用，而大多数初学者项目都会在这里遇到边界。

GitHub Pages 提供静态文件：HTML、CSS、JavaScript 和图像。它适合托管个人作品集网站、项目文档，或静态网站生成器生成的内容。它不会根据请求执行 PHP、Python 或 Node，因此登录表单、购物车或管理面板没有可供其运行的后端。

GitHub Actions 运行 CI（持续集成，即由 push 触发的自动化任务）。Runner 启动后运行测试或构建任务，随后会被销毁。两次运行之间不会有持续运行的进程，也没有可持久保留的磁盘；免费账户每月只能使用一定数量的运行分钟数。如果您需要在自己控制的硬件上运行这些任务，或需要超出该额度，可将自托管 Actions runner 指向您自己的机器。

GitHub 完全不会执行以下操作：在请求之间保持应用服务器运行、运行数据库、持续运行后台 worker、按真实计划执行 cron 任务，或存储用户上传的文件。每项功能都需要一台持续开机且归您所有的机器，这正是VPS 的定义及其提供的能力。小型项目通常采用以下结构：代码存储在 GitHub 上，应用在服务器上运行，再通过部署步骤连接两者。如果您使用 AI 编程助手构建了某个项目，并希望其他人能够访问它，将生成的应用部署到 VPS会完整展示这种分工。

您也可以完全不使用 GitHub 托管代码仓库。在自己的服务器上运行 Gitea 或 Forgejo，可以执行您刚学到的相同命令；自托管 Git 服务器选项介绍了您将获得什么，以及需要自行承担什么。先在这里熟悉工作流。命令不会改变。

FAQ

GitHub 免费吗，Student Developer Pack 增加了什么？

免费计划涵盖本指南中的所有内容。截至 2026 年 8 月，它包括无限量的公开和私有仓库、这些仓库的协作者，以及每月一定额度的 Actions 分钟数。GitHub Student Developer Pack 需要通过 GitHub Education 单独申请。GitHub Education 会先验证您是否在学校就读，审核通过后，Student Developer Pack 会在 GitHub 自有功能之外，附带其他公司的优惠。请检查您是否符合条件并提交申请。如果申请被拒绝，本指南介绍的任何功能都不会停止工作。

为什么我的 push 失败，并显示“已移除对密码身份验证的支持”？

因为 GitHub 已于 2021 年 8 月 13 日停止接受账户密码用于通过 HTTPS 执行 git 操作。密码仍可用于登录网站，但 git 现在需要其他凭据。您可以在 Settings、Developer settings 中创建 personal access token，并在 git 要求输入密码时粘贴该令牌；也可以添加 SSH key，然后使用 git remote set-url origin git@github.com:yourname/project.git 切换远程仓库。再次 push 前，使用 ssh -T git@github.com 确认密钥有效。

为什么我的提交没有出现在贡献图中？

几乎总是提交邮箱地址的问题。GitHub 会将提交中的地址与账户中的地址进行匹配，以确定提交归属。因此，输入错误或过时的 git config user.email 会导致提交在仓库中显示您的姓名，但无法关联到任何个人资料。运行 git log -1 --format='%ae' 查看最近一次提交中的地址，然后将该地址添加到账户，或修正配置。修正后只对未来的提交生效，不会改写旧提交。提交还必须位于您拥有的仓库的默认分支上，不能位于 fork 中。

招聘人员真的会查看我的 GitHub 个人资料吗？

会，但停留时间很短。他们会打开个人资料，浏览置顶仓库，再阅读某个 README 的前几行。因此，真正有价值的是让少量项目易于理解：名称清晰，用一句话说明项目用途，并提供确实能在全新机器上运行的安装和设置命令。招聘人员通常也会扫一眼贡献图，因为绿色方格只能证明您进行过提交，无法说明这些提交是否有价值。

GitHub 可以托管我的网站和后端吗？

当网站由静态文件组成时，GitHub Pages 可以托管该网站。它不运行服务器端代码，因此无法提供 Django、Express 或 Laravel 应用，无法连接数据库，也无法运行定时任务。这些功能需要一台持续运行的机器，而 VPS 就是为此提供的。通常的做法是将代码保存在 GitHub 上，再从 GitHub 部署到该服务器。