GitHub 项目托管与访问教程

一、注册GitHub账号

1.1 访问GitHub官网

打开浏览器，访问：https://github.com

1.2 创建账号

点击右上角 "Sign up"
填写以下信息：
- Email：邮箱地址
- Password：密码（至少15个字符）
- Username：用户名（将成为你的GitHub主页地址）
点击 "Continue"
完成人机验证
查收邮件，点击验证链接完成注册

1.3 登录GitHub

注册成功后，使用邮箱和密码登录。

二、创建GitHub仓库

2.1 新建仓库

登录后，点击右上角 "+" 号
选择 "New repository"

2.2 填写仓库信息

Repository name（仓库名称）规则

限制项	说明
长度	1-255个字符
字符类型	只能包含字母、数字、下划线 `_`、连字符 `-`、点 `.`
首尾字符	不能以点 `.` 开头或结尾
连续点	不能有连续的点 `..`
特殊保留名	不能使用 `help`, `gist`, `snake`, `policy`, `contact` 等
大小写	不区分大小写（GitHub会转为小写）

推荐命名方式：

使用小写字母
单词用连字符 - 分隔
简洁明了，见名知意

示例：

✅ my-project
✅ awesome-app
✅ learning-python
❌ My Project（含空格）
❌ project..test（连续点）
❌ .hidden（以点开头）

仓库信息填写

选项	说明	示例
Repository name	仓库名称	`my-project`
Description	仓库描述	`我的第一个项目`
Public/Private	`Public` 公开（任何人可见），`Private` 私有（仅自己可见）	Public
Initialize with a README	初始化README文件	建议勾选
Add .gitignore	添加忽略文件	根据项目类型选择
Choose a license	选择开源协议	MIT / Apache 2.0

点击 "Create repository" 创建仓库

2.3 获取仓库地址

创建成功后，会显示仓库地址，格式为：

复制代码

https://github.com/用户名/仓库名.git

三、安装Git

3.1 Windows系统

访问：https://git-scm.com/downloads
下载 Windows 安装包
双击运行安装程序
安装选项一路默认，点击 Next 直到完成
打开终端（CMD或PowerShell），输入以下命令验证：

git --version

显示版本号说明安装成功。

3.2 macOS系统

方法一：使用 Homebrew（推荐）

bash 复制代码

brew install git

方法二：安装Xcode Command Line Tools

bash 复制代码

xcode-select --install

验证安装：

bash 复制代码

git --version

3.3 Linux系统

bash 复制代码

# Ubuntu/Debian
sudo apt update
sudo apt install git

# CentOS/RHEL
sudo yum install git

# Fedora
sudo dnf install git

验证安装：

bash 复制代码

git --version

四、配置Git

首次使用Git需要配置用户信息，用于标识提交者。

4.1 配置用户名和邮箱

打开终端，输入以下命令（替换为你的实际信息）：

bash 复制代码

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

示例：

bash 复制代码

git config --global user.name "张三"
git config --global user.email "zhangsan@example.com"

4.2 查看配置

bash 复制代码

git config --list

4.3 配置SSH密钥（可选，推荐）

SSH方式推送无需每次输入密码。

生成SSH密钥

bash 复制代码

ssh-keygen -t ed25519 -C "你的邮箱"

一路按回车使用默认配置。

添加SSH密钥到GitHub

查看公钥内容：

bash 复制代码

cat ~/.ssh/id_ed25519.pub

复制显示的全部内容
打开 GitHub → Settings → SSH and GPG keys
点击 "New SSH key"
粘贴公钥内容，点击 "Add SSH key"

测试SSH连接

bash 复制代码

ssh -T git@github.com

看到欢迎信息说明配置成功。

五、推送本地项目到GitHub

5.1 初始化本地仓库

进入你的项目目录：

bash 复制代码

cd /path/to/your/project

初始化Git仓库：

bash 复制代码

git init

5.2 添加文件到暂存区

添加所有文件：

bash 复制代码

git add .

或添加指定文件：

bash 复制代码

git add 文件名

5.3 提交更改

bash 复制代码

git commit -m "首次提交"

5.4 关联远程仓库

使用HTTPS方式：

bash 复制代码

git remote add origin https://github.com/用户名/仓库名.git

使用SSH方式（配置了SSH的话）：

bash 复制代码

git remote add origin git@github.com:用户名/仓库名.git

5.5 推送到GitHub

bash 复制代码

# 首次推送，指定分支名
git push -u origin main

# 或者如果默认分支是master
git push -u origin master

5.6 完整流程示例

bash 复制代码

# 1. 进入项目目录
cd /Users/username/my-project

# 2. 初始化Git
git init

# 3. 添加所有文件
git add .

# 4. 提交
git commit -m "初始化项目"

# 5. 关联远程仓库
git remote add origin https://github.com/username/my-project.git

# 6. 推送
git push -u origin main

5.7 推送成功后

刷新GitHub仓库页面，就能看到你的项目文件了。

六、设置项目在线访问

想让项目通过网页直接访问，可以使用 GitHub Pages 功能。

6.1 什么是GitHub Pages

GitHub Pages 是GitHub提供的静态网页托管服务，可以免费托管个人网站、项目文档等。

访问地址格式：https://用户名.github.io/仓库名/

6.2 启用GitHub Pages

方法一：通过设置界面（推荐）

打开你的GitHub仓库
点击 Settings
左侧菜单找到 Pages
在 Build and deployment 下：
- Source : 选择 Deploy from a branch
- Branch : 选择 main 或 master
- Folder : 选择 / (root)
点击 Save

等待1-2分钟，GitHub会自动部署。

方法二：使用gh-pages分支

适用于需要构建的项目（如React、Vue等）：

bash 复制代码

# 创建gh-pages分支
git checkout -b gh-pages

# 推送
git push -u origin gh-pages

# 回到主分支
git checkout main

然后在仓库设置中，Branch选择 gh-pages。

6.3 获取访问地址

等待部署完成后，在 Pages 设置页面顶部会显示访问地址：

复制代码

https://你的用户名.github.io/仓库名/

6.4 常见项目类型的Pages配置

静态HTML项目

直接将 index.html 放在根目录即可。

React项目

bash 复制代码

# 安装gh-pages工具
npm install gh-pages --save-dev

# 在package.json添加scripts
"scripts": {
  "predeploy": "npm run build",
  "deploy": "gh-pages -d build"
}

# 部署
npm run deploy

Vue项目

bash 复制代码

# 安装gh-pages工具
npm install gh-pages --save-dev

# 在package.json添加scripts
"scripts": {
  "predeploy": "npm run build",
  "deploy": "gh-pages -d dist"
}

# 部署
npm run deploy

Next.js项目

使用 next export 导出静态文件后部署：

json 复制代码

// next.config.js
module.exports = {
  output: 'export'
}

6.5 自定义域名（可选）

在域名DNS管理中添加CNAME记录：
- 主机记录：www.你的仓库名
- 记录值：你的用户名.github.io
在仓库根目录创建 CNAME 文件，写入：
复制代码
```
www.你的域名.com
```
在GitHub Pages设置中填写自定义域名。

七、常用Git命令

7.1 基础命令

命令	说明
`git init`	初始化仓库
`git status`	查看当前状态
`git add .`	添加所有文件到暂存区
`git add 文件名`	添加指定文件
`git commit -m "说明"`	提交更改
`git push`	推送到远程仓库
`git pull`	从远程仓库拉取

7.2 查看和比较

命令	说明
`git log`	查看提交历史
`git log --oneline`	简洁显示提交历史
`git diff`	查看未暂存的修改
`git diff --staged`	查看已暂存的修改

7.3 分支管理

命令	说明
`git branch`	查看本地分支
`git branch -a`	查看所有分支
`git branch 分支名`	创建新分支
`git checkout 分支名`	切换分支
`git checkout -b 分支名`	创建并切换分支
`git branch -d 分支名`	删除分支

7.4 远程操作

命令	说明
`git remote -v`	查看远程仓库
`git remote add origin 地址`	添加远程仓库
`git remote remove origin`	删除远程仓库

7.5 撤销操作

命令	说明
`git reset HEAD 文件`	取消暂存文件
`git checkout -- 文件`	恢复文件到上次提交
`git reset --hard HEAD`	回退到上次提交

.gitignore 常用配置

在项目根目录创建 .gitignore 文件，指定不需要提交的文件：

复制代码

# Python
__pycache__/
*.py[cod]
*.so
venv/

# Node
node_modules/
npm-debug.log

# IDE
.vscode/
.idea/
*.swp

# 系统文件
.DS_Store
Thumbs.db

# 环境变量
.env

八、常见问题

Q1: 推送时提示 "Permission denied"

原因: 没有权限或认证失败

解决方法:

确认仓库URL正确
如果是HTTPS，检查是否开启了双因素认证，需要使用Personal Access Token
如果是SSH，确认SSH密钥已正确配置

Q2: 推送时提示 "remote already exists"

原因: 远程仓库已关联

解决方法:

bash 复制代码

# 先删除旧的
git remote remove origin

# 重新添加
git remote add origin 新地址

Q3: 合并冲突怎么办

解决方法:

bash 复制代码

# 拉取远程更改
git pull origin main

# 手动编辑冲突文件
# 解决后标记为已解决
git add 冲突文件

# 提交
git commit -m "解决冲突"

# 推送
git push

Q4: 如何修改最后一次提交

bash 复制代码

# 修改文件后
git add .
git commit --amend

注意：已推送的提交不建议修改。

Q5: Pages显示404错误

解决方法:

确认仓库为Public
检查Settings中Pages是否正确启用
确认根目录有 index.html 文件
等待2-3分钟，GitHub部署需要时间
查看仓库的"Actions"标签页，检查部署日志

总结

完成以上步骤后，你的项目已经成功托管到GitHub，并且可以通过GitHub Pages在线访问。

核心流程回顾：

注册GitHub账号
创建仓库
安装并配置Git
初始化并推送本地项目
启用GitHub Pages实现在线访问

推荐阅读: