GitHub注册与部署完整教程及常见错误解决方案

GitHub账号注册

步骤一：访问GitHub官网

打开浏览器，访问 https://github.com
点击右上角的 Sign up 按钮

步骤二：填写注册信息

输入邮箱地址：使用有效的电子邮箱（建议使用常用邮箱）
创建密码：至少8位字符，包含字母和数字
设置用户名：
- 只能包含字母、数字、连字符(-)
- 不能以连字符开头或结尾
- 连字符不能连续使用
- 用户名是唯一的，系统会提示是否可用

步骤三：验证账号

完成人机验证（可能需要识别图片中的物体）
点击 Create account 创建账号
查收验证邮件，点击邮件中的验证链接

步骤四：选择计划

Free（免费版）：适合个人开发者，无限公共仓库和私有仓库
Pro（付费版）：适合专业开发者，包含高级代码审查工具等
一般个人用户选择 Free 计划即可

步骤五：完善个人资料

回答一些关于编程经验的问题（可跳过）
设置个人头像
完善个人简介

Git基础配置

安装Git

Windows系统

访问 https://git-scm.com/downloads
下载Windows版本安装包
运行安装程序，保持默认选项即可
安装完成后，在命令行输入验证：
1

git --version

macOS系统

1
2
3
4
5


# 使用Homebrew安装
brew install git

# 验证安装
git --version

Linux系统

1
2
3
4
5
6
7
8
9


# Ubuntu/Debian
sudo apt-get update
sudo apt-get install git

# CentOS/RHEL
sudo yum install git

# 验证安装
git --version

配置Git用户信息

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 设置用户名（与GitHub用户名一致）
git config --global user.name "你的GitHub用户名"

# 设置邮箱（与GitHub注册邮箱一致）
git config --global user.email "your.email@example.com"

# 设置默认编辑器（可选）
git config --global core.editor "vim"

# 查看配置信息
git config --list

配置SSH密钥（推荐）

SSH密钥可以实现免密码推送代码，更加安全便捷。

1
2
3
4
5
6
7
8


# 生成SSH密钥
ssh-keygen -t ed25519 -C "your.email@example.com"

# 如果系统不支持ed25519，使用rsa
ssh-keygen -t rsa -b 4096 -C "your.email@example.com"

# 按回车键接受默认文件位置
# 可以设置密码（可选，直接回车表示不设置）

添加SSH密钥到SSH代理

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# 启动ssh-agent
# Windows (Git Bash)
eval "$(ssh-agent -s)"

# macOS
eval "$(ssh-agent -s)"

# Linux
eval "$(ssh-agent -s)"

# 添加私钥到ssh-agent
ssh-add ~/.ssh/id_ed25519
# 或
ssh-add ~/.ssh/id_rsa

添加公钥到GitHub

复制公钥内容：

1
2
3
4
5
6
7
8
9


# Windows
clip < ~/.ssh/id_ed25519.pub

# macOS
pbcopy < ~/.ssh/id_ed25519.pub

# Linux
cat ~/.ssh/id_ed25519.pub
# 手动复制输出内容

登录GitHub，点击右上角头像 → Settings
左侧菜单选择 SSH and GPG keys
点击 New SSH key
填写标题（如：My Laptop），粘贴公钥内容
点击 Add SSH key

测试SSH连接

1
2
3
4


ssh -T git@github.com

# 看到以下提示表示成功
# Hi username! You've successfully authenticated...

GitHub仓库部署

创建新仓库

登录GitHub，点击右上角 + 号 → New repository
填写仓库信息：
- Repository name：仓库名称（建议使用英文）
- Description：仓库描述（可选）
- Public/Private：公开或私有
- Initialize this repository with：
  - ☑️ Add a README file（推荐勾选）
  - ☑️ Add .gitignore（根据项目类型选择）
  - ☑️ Choose a license（可选）
点击 Create repository

本地项目推送到GitHub

方式一：克隆已有仓库

1
2
3
4
5
6
7
8


# 使用HTTPS（需要输入密码）
git clone https://github.com/username/repository.git

# 使用SSH（推荐，免密码）
git clone git@github.com:username/repository.git

# 进入项目目录
cd repository

方式二：推送本地现有项目

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


# 进入本地项目目录
cd /path/to/your/project

# 初始化Git仓库
git init

# 添加所有文件到暂存区
git add .

# 提交更改
git commit -m "Initial commit"

# 添加远程仓库（HTTPS方式）
git remote add origin https://github.com/username/repository.git

# 或添加远程仓库（SSH方式，推荐）
git remote add origin git@github.com:username/repository.git

# 推送到GitHub
git push -u origin main
# 或如果默认分支是master
git push -u origin master

常用Git操作

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


# 查看仓库状态
git status

# 查看修改内容
git diff

# 添加指定文件
git add filename.txt

# 添加所有修改
git add .

# 提交更改
git commit -m "提交说明"

# 推送到远程仓库
git push origin main

# 拉取最新代码
git pull origin main

# 查看提交历史
git log --oneline

# 创建并切换到新分支
git checkout -b feature-branch

# 切换分支
git checkout main

# 合并分支
git merge feature-branch

# 删除本地分支
git branch -d feature-branch

GitHub Pages部署静态网站

GitHub Pages可以免费托管静态网站。

方法一：通过仓库设置

进入仓库页面，点击 Settings
左侧选择 Pages
Source 选择 Deploy from a branch
Branch 选择 main 或 master，文件夹选择 /(root) 或 /docs
点击 Save
等待几分钟，访问 https://username.github.io/repository-name

方法二：使用GitHub Actions自动部署

在项目根目录创建 .github/workflows/deploy.yml：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    
    - name: Setup Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '18'
    
    - name: Install dependencies
      run: npm ci
    
    - name: Build
      run: npm run build
    
    - name: Deploy
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./dist

提交并推送，GitHub会自动构建并部署

常见错误及解决方案

1. 身份验证错误

错误信息

1

fatal: Authentication failed for 'https://github.com/username/repo.git/'

解决方案

方案A：更新凭据

Windows：控制面板 → 凭据管理器 → Windows凭据 → 删除github相关凭据
macOS：git config --global credential.helper osxkeychain，然后重新输入密码

方案B：使用Personal Access Token

GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
点击 Generate new token
选择权限范围（至少勾选 repo）
生成后复制token，代替密码使用

方案C：切换到SSH方式

1
2


# 修改远程URL为SSH
git remote set-url origin git@github.com:username/repo.git

2. 权限拒绝错误

错误信息

1
2


Permission denied (publickey).
fatal: Could not read from remote repository.

解决方案

检查SSH密钥是否正确添加：
1

ssh -T git@github.com

如果失败，重新添加密钥：

1
2
3
4
5


# 启动ssh-agent
eval "$(ssh-agent -s)"

# 添加密钥
ssh-add ~/.ssh/id_ed25519

确认公钥已添加到GitHub账户

3. 仓库不存在错误

错误信息

1

fatal: repository 'https://github.com/username/repo.git/' not found

解决方案

检查仓库URL是否正确
确认仓库是否存在（可能已被删除或设为私有）
如果是私有仓库，确认有访问权限
检查网络连接

4. 推送被拒绝错误

错误信息

1
2


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

解决方案

1
2
3
4
5
6
7
8


# 先拉取远程更新
git pull origin main

# 如果有冲突，解决冲突后重新推送
git push origin main

# 或者强制推送（会覆盖远程更改，慎用）
git push -f origin main

5. 合并冲突

错误信息

1
2


CONFLICT (content): Merge conflict in filename.txt
Automatic merge failed; fix conflicts and then commit the result.

解决方案

打开冲突文件，查找冲突标记：

1
2
3
4
5


<<<<<<< HEAD
本地代码
=======
远程代码
>>>>>>> branch-name

编辑文件，保留需要的代码，删除冲突标记

标记为已解决并提交：

1
2
3


git add .
git commit -m "Resolve merge conflict"
git push origin main

6. 大文件推送失败

错误信息

1

remote: error: File largefile.zip is 156.78 MB; this exceeds GitHub's file size limit of 100.00 MB

解决方案

方案A：使用Git LFS（大文件存储）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


# 安装Git LFS
git lfs install

# 追踪大文件
git lfs track "*.zip"
git lfs track "*.psd"

# 提交.gitattributes
git add .gitattributes
git commit -m "Track large files with LFS"

# 重新添加大文件并推送
git add largefile.zip
git commit -m "Add large file"
git push origin main

方案B：从提交历史中删除大文件

1
2


# 使用BFG Repo-Cleaner或filter-branch
# 参考GitHub文档：https://docs.github.com/en/repositories/working-with-files/managing-large-files

7. 邮箱隐私错误

错误信息

1

remote: error: GH007: Your push would publish private email addresses.

解决方案

GitHub → Settings → Emails
取消勾选 Keep my email addresses private

或使用GitHub提供的noreply邮箱：

1

git config --global user.email "username@users.noreply.github.com"

8. 连接超时错误

错误信息

1

fatal: unable to access 'https://github.com/...': Failed to connect to github.com port 443: Timed out

解决方案

方案A：配置代理

1
2
3
4
5
6
7


# 设置HTTP代理
git config --global http.proxy http://proxy.example.com:8080
git config --global https.proxy https://proxy.example.com:8080

# 取消代理
git config --global --unset http.proxy
git config --global --unset https.proxy

方案B：使用SSH方式 SSH连接通常比HTTPS更稳定

方案C：修改hosts文件 查找GitHub的最新IP地址并添加到hosts文件

9. 分支不存在错误

错误信息

1

error: pathspec 'main' did not match any file(s) known to git

解决方案

1
2
3
4
5
6
7
8
9


# 查看所有分支
git branch -a

# 创建并切换到新分支
git checkout -b main

# 或从远程拉取分支
git fetch origin
git checkout -b main origin/main

10. 提交信息错误修改

修改最后一次提交

1
2
3
4
5
6
7
8
9


# 修改提交信息
git commit --amend -m "新的提交信息"

# 修改提交内容（添加遗漏的文件）
git add forgotten-file.txt
git commit --amend --no-edit

# 强制推送到远程（如果已推送）
git push --force-with-lease origin main

总结

GitHub是全球最大的代码托管平台，掌握其注册和部署流程对开发者至关重要。本文涵盖了：

注册流程：从账号创建到邮箱验证
Git配置：安装、用户信息设置、SSH密钥配置
部署方法：仓库创建、代码推送、GitHub Pages部署
常见问题：10种常见错误及详细解决方案

建议新手：

优先使用SSH方式连接，避免反复输入密码
养成经常commit和push的习惯
遇到问题时仔细阅读错误信息
善用GitHub官方文档和社区资源

参考资源