GitHub 新建项目操作指南

GitHub 新建项目的详细操作步骤，适用于网页版

一、准备工作

注册/登录 GitHub 账号
准备项目相关材料
- 项目名称
- 项目描述（可选）
- README 文件内容
- .gitignore 模板（可选）
- 开源许可证（可选）

二、创建新仓库

从零开始创建

登录 GitHub，点击右上角 + 图标
选择 New repository
填写仓库信息：
- Repository name : 项目名称（如 my-project）
- Description: 项目描述（可选）
- Visibility:
  - Public（公开，免费）
  - Private（私有，免费用户可用）
- 初始化选项（保持默认）：
  - ✅ Add a README file（添加说明文档）
  - ✅ Add .gitignore（选择模板：如 Python、Node 等）
  - ✅ Choose a license（选择开源协议：如 MIT、Apache 等）
点击 Create repository

三、本地连接与操作

情况一：本地已有项目代码

bash

复制代码

# 1. 进入项目目录
cd your-project

# 2. 初始化 Git
git init

# 3. 添加远程仓库
git remote add origin https://github.com/用户名/仓库名.git

# 4. 添加文件并提交
git add .
git commit -m "Initial commit"

# 5. 推送到 GitHub
git branch -M main
git push -u origin main

情况二：从零开始新项目

bash

复制代码

# 1. 克隆空仓库到本地
git clone https://github.com/用户名/仓库名.git
cd 仓库名

# 2. 创建项目文件
# ... 编写代码 ...

# 3. 提交更改
git add .
git commit -m "添加功能"
git push origin main

四、仓库设置建议

添加协作成员（私有仓库）：
- Settings → Collaborators → Add people
设置分支保护规则：
- Settings → Branches → Add rule
配置项目页面：
- Settings → Pages → 选择分支和文件夹
管理 Webhooks 和集成（可选）

五、快速操作技巧

通过命令行创建（需要 GitHub CLI）：

bash
复制代码
```
gh repo create 仓库名 --public --clone
```
从现有代码导入：
- 在仓库页面点击 Import code
使用 GitHub Desktop：
1. 安装 GitHub Desktop
2. File → New repository
3. 同步到 GitHub

常见问题

推送失败：检查远程地址和权限
文件忽略无效：确认 .gitignore 语法正确
许可证选择：根据项目需求选择合适的开源协议

下一步建议

完善 README.md（项目介绍、安装、使用说明）
添加 Issues 模板
设置 CI/CD 工作流程
创建第一个版本 Release

推送失败：SSH 公钥认证被拒绝（git@github.com 权限不足）并且主机密钥已添加到 ~/.ssh/known_hosts。

SSH 公钥认证被拒绝是常见的权限问题。以下是详细的排查和解决方案：

一、问题诊断步骤

1. 检查 SSH 密钥是否存在

bash

复制代码

# 查看本地是否有 SSH 密钥
ls -al \~/.ssh/
# 应该能看到 id_rsa 和 id_rsa.pub（或 id_ed25519 等）

2. 测试 SSH 连接

bash

复制代码

ssh -T git@github.com

预期成功响应：

text

复制代码

Hi 你的用户名! You've successfully authenticated...

错误响应：

Permission denied (publickey)：密钥未正确配置
Host key verification failed：known_hosts 问题

二、解决方案

方案 A：重新添加公钥到 GitHub

复制公钥内容：

bash

复制代码

# 复制 RSA 密钥
cat ~/.ssh/id_rsa.pub

# 或者 ed25519 密钥
cat ~/.ssh/id_ed25519.pub

注意：复制 .pub 文件内容，格式类似：

text

复制代码

ssh-rsa AAAAB3NzaC1yc2EAAA... 你的邮箱

在 GitHub 添加公钥：
- 登录 GitHub → Settings → SSH and GPG keys
- 点击 New SSH key
- Title：自定义名称（如 "My Laptop"）
- Key：粘贴刚才复制的公钥内容
- 点击 Add SSH key

方案 B：生成新的 SSH 密钥

如果现有密钥无效或丢失：

bash

复制代码

# 1. 生成新密钥（推荐 ed25519）
ssh-keygen -t ed25519 -C "your_email@example.com"

# 或使用 RSA
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

# 2. 一路回车使用默认设置
# 3. 启动 SSH 代理
eval "$(ssh-agent -s)"

# 4. 添加私钥到代理
ssh-add ~/.ssh/id_ed25519  # 或 id_rsa

# 5. 复制公钥并添加到 GitHub（如方案 A 步骤）
cat ~/.ssh/id_ed25519.pub | pbcopy  # macOS
cat ~/.ssh/id_ed25519.pub | clip    # Windows
cat ~/.ssh/id_ed25519.pub           # Linux，手动复制

方案 C：检查 known_hosts 文件

bash

复制代码

# 1. 删除旧的 GitHub 主机密钥
ssh-keygen -R github.com

# 2. 重新添加
ssh-keyscan github.com >> ~/.ssh/known_hosts

三、验证和测试

1. 测试 SSH 连接

bash

复制代码

ssh -T git@github.com -v

-v 参数显示详细调试信息，帮助定位问题。

2. 检查 Git 远程 URL

bash

复制代码

# 查看当前远程地址
git remote -v

# 如果不是 SSH 格式，修改为 SSH
git remote set-url origin git@github.com:用户名/仓库名.git

# 从 HTTPS 切换到 SSH 的示例：
git remote set-url origin git@github.com:username/repo.git

3. 多密钥配置（如果使用多个 GitHub 账号）

在 ~/.ssh/config 文件中添加：

bash

复制代码

# 编辑配置文件
nano ~/.ssh/config

# 添加以下内容
Host github.com-personal
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_personal

Host github.com-work
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_work

# 使用不同的远程 URL
git remote set-url origin git@github.com-work:公司账号/仓库名.git

四、常见错误及解决

错误 1：Agent admitted failure

bash

复制代码

# 解决方案
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_rsa  # 或你的私钥文件

错误 2：Permissions are too open

bash

复制代码

# 修复文件权限
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_rsa
chmod 644 ~/.ssh/id_rsa.pub
chmod 644 ~/.ssh/known_hosts

错误 3：Windows 特定问题

确保 OpenSSH 服务运行：

powershell

复制代码

# 管理员 PowerShell
Get-Service ssh-agent
Set-Service ssh-agent -StartupType Automatic
Start-Service ssh-agent

使用 Git Bash 替代 PowerShell

五、快速检查清单

SSH 密钥已生成且存在
公钥已添加到 GitHub
SSH 代理正在运行
私钥已添加到代理
Git 远程 URL 是 SSH 格式
文件权限正确

六、备用方案：使用 HTTPS

如果 SSH 问题暂时无法解决，可临时使用 HTTPS：

bash

复制代码

# 切换为 HTTPS
git remote set-url origin https://github.com/用户名/仓库名.git

# 推送时使用个人访问令牌（PAT）
# 在 GitHub Settings → Developer settings → Personal access tokens 生成
git push origin main
# 输入用户名，密码处粘贴 PAT

七、调试命令汇总

bash

复制代码

# 完整调试流程
ssh -T git@github.com -v                    # 详细调试
ssh-add -l                                  # 列出加载的密钥
cat ~/.ssh/config 2>/dev/null || echo "无配置文件"  # 检查配置
git config --get remote.origin.url          # 检查远程 URL

total 12 drwx------ 2 mumu mumu 4096 Dec 12 13:07 . drwxr-x--- 13 mumu mumu 4096 Dec 12 13:07 .. -rw-r--r-- 1 mumu mumu 142 Dec 12 13:07 known_hosts

你的 SSH 目录只有 `known_hosts` 文件

说明还没有生成 SSH 密钥对。这是问题的根本原因。让我们一步步解决：

一、生成新的 SSH 密钥

1. 生成密钥对

bash

复制代码

# 使用 ed25519 算法（更安全、更快）
ssh-keygen -t ed25519 -C "你的邮箱@example.com"

# 或者使用 RSA 算法（兼容性更好）
# ssh-keygen -t rsa -b 4096 -C "你的邮箱@example.com"

执行上述命令后：

按 Enter 接受默认保存路径（~/.ssh/id_ed25519）
设置密码（可选）：可以为空直接按 Enter
再次确认密码（如果设置了）

2. 验证密钥生成

bash

复制代码

# 查看生成的密钥文件
ls -la ~/.ssh/

# 应该能看到：
# - id_ed25519      （私钥，权限 600）
# - id_ed25519.pub  （公钥，权限 644）
# - known_hosts

二、添加 SSH 密钥到代理

1. 启动 SSH 代理

bash

复制代码

# 启动代理
eval "$(ssh-agent -s)"
# 应该看到类似：Agent pid 12345

2. 添加私钥到代理

bash

复制代码

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

# 如果使用 RSA
# ssh-add ~/.ssh/id_rsa

3. 验证密钥已加载

bash

复制代码

ssh-add -l
# 应该显示指纹信息，如：256 SHA256:xxxxxxxxxx your_email@example.com (ED25519)

三、将公钥添加到 GitHub

1. 复制公钥内容

bash

复制代码

# 显示公钥内容并复制
cat \~/.ssh/id_ed25519.pub

公钥内容格式：

复制代码

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... 你的邮箱@example.com

复制全部内容 （以 ssh-ed25519 开头，邮箱结尾）

2. 添加到 GitHub

打开浏览器登录 GitHub
点击右上角头像 → Settings
左侧菜单选择 SSH and GPG keys
点击 New SSH key
填写：
- Title：自定义（如 "My Laptop"）
- Key type：保持默认 Authentication Key
- Key：粘贴刚才复制的公钥内容
点击 Add SSH key

四、测试 SSH 连接

1. 测试 GitHub 连接

bash

复制代码

ssh -T git@github.com

成功响应：

复制代码

Hi 你的用户名! You've successfully authenticated, but GitHub does not provide shell access.

2. 如果仍然失败，清理 known_hosts

bash

复制代码

# 删除旧的 GitHub 主机密钥
ssh-keygen -R github.com

# 重新连接，会自动添加
ssh -T git@github.com

五、配置 Git 使用 SSH

1. 检查当前远程地址

bash

复制代码

cd 你的项目目录
git remote -v

2. 如果是 HTTPS，切换为 SSH

看情况，不一定要切换。

推送失败：SSH 公钥认证被拒绝（git@github.com 权限不足）并且主机密钥已添加到 ~/.ssh/known_hosts。

可选操作（请回复选择一项）：

我帮你改用 HTTPS URL 并推送（我会将 remote 设置为 https://github.com/IreneJinqiu/Vue3-study.git 并尝试推送；可能需要输入凭据）。

你提供已配置的 SSH key 或在当前环境配置 SSH 后我再重试。

我只把远程添加好（现在已经设置为 git@github.com:IreneJinqiu/Vue3-study.git），你在本地处理认证后再推送。

已配置 SSH key，重试

现在我将确认当前分支并使用已配置的 SSH key 推送到 origin（检查分支、执行 git push）。

git branch --show-current

git push -u origin master

已完成：当前分支 master 已成功推送到远程 origin（git@github.com:IreneJinqiu/Vue3-study.git），并设置为跟踪 origin/master。

bash

复制代码

# 格式：git@github.com:用户名/仓库名.git
git remote set-url origin git@github.com:你的用户名/仓库名.git

# 示例：
# git remote set-url origin git@github.com:mumu/my-project.git

3. 测试推送

bash

复制代码

git push origin main

六、完整命令序列（直接复制执行）

bash

复制代码

# 1. 生成 SSH 密钥（使用你的邮箱）
ssh-keygen -t ed25519 -C "mumu@example.com"

# 一路按 Enter，使用默认设置

# 2. 启动 SSH 代理
eval "$(ssh-agent -s)"

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

# 4. 显示公钥（复制全部内容）
cat ~/.ssh/id_ed25519.pub

# 5. 测试连接
ssh -T git@github.com

# 6. 进入项目目录，切换到 SSH
cd ~/你的项目路径
git remote set-url origin git@github.com:你的用户名/仓库名.git
git push origin main

七、快速排查

如果还有问题，检查以下几点：

文件权限是否正确：

bash

复制代码

chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub

检查是否使用 VPN 或代理：有些网络会拦截 SSH
多账号配置 ：如果使用多个 GitHub 账号，需要配置 ~/.ssh/config

请先执行第 1-4 步（生成密钥并添加到 GitHub），然后告诉我测试 ssh -T git@github.com 的结果，我会根据具体错误进一步帮助您。

GitHub 新建项目操作指南

GitHub 新建项目的详细操作步骤，适用于网页版

一、准备工作

二、创建新仓库

从零开始创建

三、本地连接与操作

情况一：本地已有项目代码

情况二：从零开始新项目

四、仓库设置建议

五、快速操作技巧

常见问题

下一步建议

推送失败：SSH 公钥认证被拒绝（git@github.com 权限不足）并且主机密钥已添加到 ~/.ssh/known_hosts。

一、问题诊断步骤

1. 检查 SSH 密钥是否存在

2. 测试 SSH 连接

二、解决方案

方案 A：重新添加公钥到 GitHub

方案 B：生成新的 SSH 密钥

方案 C：检查 known_hosts 文件

三、验证和测试

1. 测试 SSH 连接

2. 检查 Git 远程 URL

3. 多密钥配置（如果使用多个 GitHub 账号）

四、常见错误及解决

错误 1：Agent admitted failure

错误 2：Permissions are too open

错误 3：Windows 特定问题

五、快速检查清单

六、备用方案：使用 HTTPS

七、调试命令汇总

你的 SSH 目录只有 known_hosts 文件

一、生成新的 SSH 密钥

1. 生成密钥对

2. 验证密钥生成

二、添加 SSH 密钥到代理

1. 启动 SSH 代理

2. 添加私钥到代理

3. 验证密钥已加载

三、将公钥添加到 GitHub

1. 复制公钥内容

2. 添加到 GitHub

四、测试 SSH 连接

1. 测试 GitHub 连接

2. 如果仍然失败，清理 known_hosts

五、配置 Git 使用 SSH

1. 检查当前远程地址

2. 如果是 HTTPS，切换为 SSH

3. 测试推送

六、完整命令序列（直接复制执行）

七、快速排查

你的 SSH 目录只有 `known_hosts` 文件