企业官网建设流程全解析

• 文档
• 教程
• 开源治理

导读：本文基于 first-contributions 仓库及其波斯语译本 README.fa.md 整理。first-contributions 是一个专为开源新手设计的练习仓库——你只需在 Contributors.md 中加上自己的名字并提交一个 Pull Request，就能完整走通开源协作的标准流程。读完本文，你将掌握fork → clone → branch → edit → commit → push → pull request这一套 GitHub 协作的核心链路，并学会处理推送认证失败等常见问题，为真正参与其他开源项目打好基础。

一、项目定位：为什么需要一个"练习仓库"

开源项目的首次贡献往往卡在"万事开头难"：不知道流程、怕改坏别人的代码、不熟悉git命令。first-contributions 正是为降低这个门槛而生——它把"首次贡献"变成了一个零风险、可反复练习的沙盒：你要修改的只是一个纯文本名单文件 Contributors.md（当前仓库中该文件已积累数千行贡献者名单），不会涉及任何业务代码。

该仓库本身没有可运行的源码或测试框架，它的"产品"就是这份教程文档体系：

• 根目录 README.md 提供基于命令行（CLI）的英文教程；
• docs/translations 目录收录了数十种语言的 README 译本（其中就包括本文依据的 波斯语译本 README.fa.md），方便全球新手用母语学习；
• docs/additional-material 提供 Git 进阶技巧（修改提交、解决冲突、合并提交等）；
• docs/gui-tool-tutorials 提供 GitHub Desktop、VS Code、GitKraken 等图形化工具的替代教程。

二、前置准备：安装 Git

在开始之前，请确认你的机器上已经安装了git。在终端中执行以下命令即可验证：

git --version

如果尚未安装，请根据你的操作系统选择安装方式：

• Ubuntu/Debian：参考 installing-git-ubuntu.zh-cn.md；
• Arch Linux：参考 installing-git-arch.zh-cn.md；
• 其他平台：可参考仓库中 configuring-git.md 对 Git 全局配置的介绍，安装完成后建议先配置用户名与邮箱：

git config --global user.name "你的名字" git config --global user.email "你的邮箱"

说明：原教程中指向 Git 官方安装文档的链接为外部站点，本文不再重复给出外部地址；以上仓库内的安装文档均可直接查阅。

三、第一步：Fork（派生）这个仓库

Fork 的作用是在你自己的 GitHub 账号下创建一份目标仓库的完整副本。它不会影响原仓库，所有后续的改动都发生在你的副本上，这正是开源协作"先复制、再修改、后合并"的基本模型。

操作步骤：

1. 打开 first-contributions 仓库页面；
2. 点击页面右上角的Fork按钮；
3. 稍等片刻，你的账号下就会出现一个名为first-contributions的新仓库。

此时你拥有的是"上游"（upstream，即原仓库）的一个独立拷贝，之后对它的任何操作都不会打扰原仓库。

四、第二步：Clone（克隆）到本地

Fork 只是把仓库复制到了你的 GitHub 账号上，要编辑文件还需要把它克隆到本地电脑。

4.1 复制克隆地址

进入你账号下的 fork 仓库页面：

1. 点击绿色的Code按钮；
2. 在弹出面板中选择协议（HTTPS 或 SSH）；
3. 点击复制到剪贴板（copy to clipboard）图标，得到克隆地址。

4.2 执行克隆命令

打开终端，运行：

git clone "url you just copied"

其中"url you just copied"替换为你刚复制的地址（不要带引号）。例如：

git clone https://github.com/this-is-you/first-contributions.git

把示例中的this-is-you换成你的 GitHub 用户名。命令执行后，仓库的全部内容会被复制到本地当前目录下的first-contributions文件夹中。

4.3 进入仓库目录

克隆完成后，进入该目录（如果当前不在其中）：

cd first-contributions

提示：查看本地仓库与远端（remote）的对应关系，可以随时执行git remote -v。它会列出origin（你 fork 的仓库）的 fetch/push 地址，后续排查推送问题时会用到这个命令。

五、第三步：创建分支（Branch）

开源协作的黄金准则是：永远不要在主干分支上直接改代码，而是为每次改动新建一个独立分支，这样既便于并行开发，也便于维护者审查。

在仓库目录内执行：

git checkout -b your-new-branch-name

git checkout -b的含义是"创建并切换到一个新分支"，其中your-new-branch-name换成你的分支名。例如：

git checkout -b add-alonzo-church

分支命名约定：教程建议分支名以add开头（如add-你的名字）。虽然这不是强制要求，但当你本次贡献就是"把自己的名字加入名单"时，这种命名能直观表达分支的用途，属于开源社区的常见惯例。

关于git switch的补充：仓库英文版 README.md 中推荐使用较新的git switch -c语法（两者等价），例如git switch -c add-alonzo-church。如果你的 Git 版本较老，执行git switch会报错switch is not a git command，此时回退到git checkout -b即可。本文沿袭波斯语译本采用的git checkout -b写法，兼容性最好。

六、第四步：做出修改并提交（Commit）

6.1 修改 Contributors.md

用任意文本编辑器打开仓库根目录下的 Contributors.md 文件，把你的名字加入名单中。这里有三个注意事项：

1. 不要把名字加在文件开头或末尾——刻意加在中间，是为了模拟"与别人的改动共存"的真实协作场景，同时锻炼你处理相邻改动冲突的能力；
2. 保持与已有条目一致的格式（一般形如- 你的名字）；
3. 保存文件。

6.2 用 git status 查看改动

在仓库目录执行：

git status

你会看到Contributors.md出现在 "Changes not staged for commit"（未暂存的改动）列表中。git status是协作中最常用的"体检命令"，它能随时告诉你：当前在哪个分支、哪些文件被修改、哪些改动已暂存。

6.3 用 git add 暂存改动

git add Contributors.md

git add会把指定文件的改动放入暂存区（staging area）。如果想一次性暂存全部改动，也可以使用git add .，但精确到文件名是更安全的习惯。

6.4 用 git commit 提交

git commit -m "Add <your-name> to Contributors list"

把<your-name>替换为你的真实名字，例如：

git commit -m "Add Alonzo Church to Contributors list"

-m参数用于直接给出提交说明。一条清晰、有信息量的提交信息是开源协作的基本素养——维护者正是通过提交信息来理解你改了什么、为什么改。

七、第五步：推送（Push）到远端

本地提交完成，接下来把分支推送到你 fork 的远端仓库：

git push origin <add-your-branch-name>

把<add-your-branch-name>替换为你之前创建的分支名（例如add-alonzo-church）。更推荐加上-u参数首次推送：

git push -u origin your-branch-name

-u（即--set-upstream）会建立本地分支与远端分支的跟踪关系，之后在本分支上只需git push即可，无需再指定远端和分支名。

7.1 推送报错怎么办：认证问题排查

推送失败是新手最常遇到的坑。仓库英文版 README.md 给出了典型的认证错误排查流程，摘录如下。

症状：推送时出现类似下面的报错：

remote: Support for password authentication was removed on August 13, 2021. remote: Please use a personal access token instead. fatal: Authentication failed for 'https://github.com/<your-username>/first-contributions.git/'

原因：GitHub 已不再接受账号密码方式推送代码，需要改用 SSH 密钥或 Personal Access Token 认证。

排查步骤：

1. 先确认你的远端地址配置：

git remote -v

2. 如果输出形如：

origin https://github.com/your-username/your_repo.git (fetch) origin https://github.com/your-username/your_repo.git (push)

说明当前使用的是 HTTPS 协议，存在用户名/密码认证的兼容问题。可以改用 SSH 方式：

git remote set-url origin git@github.com:your-username/your_repo.git

3. 将你的 SSH 公钥添加到 GitHub 账号后重新推送。

进阶阅读：关于认证与凭据管理的更多细节，仓库还提供了 storing-credentials.md，其中也提示了凭据存储涉及安全问题，请遵循你所在组织/学校的安全策略。

八、第六步：提交 Pull Request（PR）

推送成功后，打开你 GitHub 账号下的 fork 仓库页面，会看到页面顶部出现一个显眼的Compare & pull request按钮，点击它。

随后你会进入 Pull Request 创建页面：

1. 检查比较方向：确保 base（目标仓库分支）是你想要合入的源仓库分支，compare（来源分支）是你刚推送的分支；
2. 填写标题与描述：用一句话说清楚本次改动做了什么（例如 "Add my name to Contributors list"）；
3. 点击Create pull request提交。

提交之后，项目维护者会看到你的 PR 并进行审查，审查通过后会把你的改动合并进项目主分支（原教程中表述为 master 分支）。合并完成后，你会收到一封通知邮件。

至此，你已经完整地走了一遍开源贡献的标准流程。

九、接下来可以做什么

9.1 庆祝并分享

首次 PR 被合并后，你可以在 firstcontributions 官方 Web 应用 中分享你的成果，让朋友和关注者看到你的第一步。（该地址为教程文档中提供的项目配套站点。）

9.2 继续深化 Git 技能

首次提交后，强烈建议阅读 additional-material.md（中文版见 additional-material.zh-cn.md），它汇总了协作中几乎一定会用到的进阶技巧，包括：

其中"保持 fork 同步"尤其重要：随着时间推移，上游仓库会不断更新，学会用git fetch upstream与git merge同步你的 fork，是持续参与开源项目的必备能力。

9.3 图形化工具替代方案

如果你对命令行（CLI）不太适应，仓库还提供了一套完整的图形化工具教程，流程与本文完全等价：

9.4 开始真实项目贡献

练习结束后，就可以把同样的流程迁移到真实项目上了。官方 Web 应用维护着一个"含易上手 issue 的项目清单"（即 firstcontributions.github.io 中的项目列表），可以作为你挑选第一个真实贡献目标的起点。从"练习仓库"走向"真实项目"，唯一不变的正是本文反复演练的这套 fork → clone → branch → commit → push → PR 工作流。

十、总结

回顾一下完整命令序列（在仓库目录内依次执行）：

# 1. 克隆你 fork 的仓库 git clone https://github.com/this-is-you/first-contributions.git cd first-contributions # 2. 创建并切换到新分支 git checkout -b add-your-name # 3. 编辑 Contributors.md，加入你的名字 # （用编辑器修改文件） # 4. 查看改动 → 暂存 → 提交 git status git add Contributors.md git commit -m "Add your-name to Contributors list" # 5. 推送到远端 git push -u origin add-your-name

之后回到 GitHub 页面点击Compare & pull request提交 PR。这份流程你将在今后的每一次开源贡献中反复使用，first-contributions 的价值就在于：用最安全的练习环境，让你在真正"上战场"之前，就把每一步都走熟。祝你贡献愉快！

• 文档
• 教程
• 开源治理