适配场景：本地文件同步到GitHub新仓库（含公共/私密仓库），解决分支不匹配、SSH端口拦截、身份验证等常见问题，优先推荐HTTPS方案（绕开网络限制，成功率100%）。

一、前置准备

  1. 安装Git：从Git官网下载对应系统版本，默认安装即可（Windows需勾选“添加到环境变量”）。
  2. GitHub账号：已注册并登录，拥有目标仓库的操作权限（所有者/协作者，私密仓库必备）。
  3. 个人访问令牌（PAT，私密仓库HTTPS推送必备）：
    1. 登录GitHub → 右上角头像 → Settings → 下拉找到 Developer settings → Personal access tokens → Generate new token。
    2. 填写备注（如“同步本地文件”），过期时间选「No expiration」（长期有效）。
    3. 权限勾选：仅需勾选 repo（包含所有仓库操作权限，满足私密仓库需求）。
    4. 点击「Generate token」，复制生成的令牌（仅显示一次，务必保存）。

二、GitHub创建新空仓库

  1. 登录GitHub → 右上角「+」→ 「New repository」。
  2. 填写仓库信息：
    1. Repository name：输入仓库名（如code-study-note，需唯一）。
    2. Description（可选）：填写仓库描述（如“编程学习笔记”）。
    3. Visibility：选择「Public」（公共）或「Private」（私密）。
    4. 关键设置：不勾选「Initialize this repository with a README」「Add .gitignore」「Choose a license」（保持仓库为空，避免与本地文件冲突）。
  3. 点击「Create repository」，创建成功后复制仓库的HTTPS地址（格式：https://github.com/你的用户名/仓库名.git）。

三、本地文件配置与推送（核心步骤）

全程在「本地文件所在目录」执行操作，以Windows为例（Mac/Linux操作命令一致，仅目录路径格式不同）。

场景1：本地文件夹未初始化Git仓库（绝大多数情况）

如何辨别是否初始化：看当前文件夹内是否存在名称为.git的文件夹，如果不存在，则说明未初始化。

  1. 打开终端：Windows按「Win+R」输入cmd打开CMD，或使用PowerShell。

  2. 进入本地文件目录（替换为你的实际路径）： cd E:\MyCode\我的编程学习笔记

  3. 执行代码，初始化本地Git仓库： git init

    执行后目录下会生成隐藏的.git文件夹（证明初始化成功）。

  4. （可选）创建.gitignore文件（排除无需同步的文件）： 在本地目录新建文本文档，重命名为.gitignore（无后缀），写入需要排除的文件/文件夹，示例：

    1
    2
    3
    4
    5
    6
    7
    8
    # 排除node_modules文件夹 
    node_modules/ 

    # 排除日志文件 
    *.log 

    # 排除环境变量文件 
    .env

  5. 将本地文件添加到Git暂存区：

    1
    2
    git add .  
    # .表示当前目录下所有文件，也可指定单个文件（如git add README.md）

  6. 提交暂存区文件到本地仓库（必须添加提交说明）： 

    1
    2
    3
    git commit -m "首次提交：同步编程学习笔记到GitHub"  

    # 备注内容可自定义

  7. 关联GitHub远程仓库（粘贴步骤1复制的HTTPS地址）：

    git remote add origin https://github.com/aboucide/code-study-note.git

  8. 推送本地文件到GitHub： git push -u origin main说明：-u 用于关联本地main分支与远程main分支，后续推送可简化为git push。

  9. 身份验证（私密仓库必现，公共仓库可选）：

    1. 终端提示输入「用户名」：输入你的GitHub账号名（如aboucide）。
    2. 提示输入「密码」：粘贴步骤0准备的「个人访问令牌（PAT）」（不可输入GitHub登录密码），回车即可。

  10. 验证结果：推送完成后，刷新GitHub仓库页面，即可看到本地文件已同步。

场景2：本地文件夹已初始化Git仓库（已有.git文件夹）

  1. 进入本地文件目录，确认本地已有提交记录（无提交则先执行提交）：

    ​ git log --oneline # 有输出说明有提交；无输出则执行git add . + git commit -m "备注"

  2. 删除原有远程仓库关联（若之前配置过错误地址）： git remote rm origin

  3. 关联新的GitHub远程仓库（HTTPS地址）：

    git remote add origin https://github.com/aboucide/code-study-note.git

  4. 推送本地文件： git push -u origin main

  5. 完成身份验证（同场景1步骤8），推送成功后验证结果。

四、常见问题与解决方案（避坑重点）

问题1：error: src refspec main does not match any（分支不匹配/无提交）

  1. 原因：本地无main分支（旧版Git默认分支为master），或无有效提交记录。
  2. 解决：
    1. 分支不匹配：将本地master分支重命名为main，再推送： git branch -M main # -M强制重命名 ``git push -u origin main
    2. 无提交记录：先完成本地提交： git add . ``git commit -m "首次提交：备注内容" ``git push -u origin main

问题2：ssh: connect to host github.com port 22: Connection refused（SSH端口拦截）

  1. 原因：网络环境（防火墙、公司/校园网）拦截了SSH默认的22端口，导致连接失败。
  2. 解决：改用HTTPS方案（优先推荐，无需修改网络配置），步骤见「步骤2」中的关联HTTPS地址并推送。

问题3：fatal: Authentication failed（身份验证失败）

  1. 原因：HTTPS推送时输入了GitHub登录密码（已被禁用），或PAT权限不足/失效。
  2. 解决：
    1. 使用PAT作为密码：重新执行git push，密码栏粘贴正确的PAT。
    2. 重新创建PAT：若PAT丢失/失效，按「前置准备」步骤重新创建，确保勾选repo权限。
    3. 确认权限：若为他人共享的私密仓库，需让仓库所有者添加你的GitHub账号为协作者（授予Write权限）。

五、后续日常同步简化流程

首次推送时已用-u关联本地与远程分支，后续本地修改文件后，仅需3步即可推送：

1
2
3
4
5
6
7
8
# 1. 添加修改的文件到暂存区
git add .

# 2. 提交到本地仓库（备注修改内容）
git commit -m "修改说明：补充Python学习笔记"

# 3. 推送至GitHub（简化命令，无需指定origin和main）
git push

六、核心总结

  1. 核心流程：GitHub创建空仓库 → 本地初始化Git → 提交本地文件 → 关联远程仓库 → 推送+身份验证。
  2. 避坑关键：① 新建仓库不勾选初始化选项；② 优先用HTTPS方案绕开SSH端口拦截；③ 私密仓库推送用PAT代替密码。
  3. 关键命令：git init（初始化）、git add .（添加文件）、git commit -m "备注"（本地提交）、git remote add origin 地址（关联远程）、git push -u origin main（首次推送）。