企业官网建设流程全解析

简介：本资源是一份面向初学者的 Git 与 GitHub 入门实践指南，适用于刚接触版本控制的开发者、学生及自学编程者，系统解决「如何将本地代码规范上传至 GitHub 远程仓库」这一核心问题。文档以清晰步骤串联注册建仓、Git 客户端安装（msysgit + TortoiseGit）、SSH 密钥配置、全局用户信息设置、add/commit/push 提交流程、.gitignore 文件编写规范，以及 tag 创建与共享等关键操作，并附有常见命令说明与排错提示（如 SSH 认证验证、远程地址配置、多版本标签管理）。资源为单个 Word 文档（.docx），共 1 个文件，大小仅 52KB，内容精炼、图文结合度高，便于快速查阅与实操对照。目前已有 1061 人学习下载，适合作为 Git 入门第一手参考资料，帮助读者建立从本地开发到云端协作的完整工作流认知。

1. 为什么“用 git 上传代码到 GitHub”不是一句命令能解决的事？——新手卡在第 1 步，老手栽在第 3 次 push

你刚写完一个 Python 脚本，想把它存到 GitHub 上备份、协作或当作品集展示。你搜到“git 上传代码到 github”，点开教程，照着敲了git init、git add .、git commit -m "first"，然后复制仓库地址，敲下git remote add origin https://github.com/xxx/yyy.git，再git push -u origin main……结果终端突然卡住、报错fatal: unable to access 'https://github.com/xxx/yyy.git/': Could not resolve host: github.com，或者更玄学的Authentication failed for 'https://github.com/xxx/yyy.git/'。你刷新 GitHub 页面，仓库还是空的。这不是你手速慢，也不是网不好——这是本地 Git 环境、远程仓库状态、认证机制、分支命名规范四者没对齐造成的系统性阻塞。它不挑人：Windows 新手会困在 SSH 密钥生成失败，Mac 用户常被默认分支名mainvsmaster绊倒，Linux 老手也可能因.gitignore里漏写__pycache__/导致上传了千个临时文件。本文不讲“Git 是什么”，只聚焦一件事：从git init到 GitHub 仓库真实显示你的代码文件，每一步为什么必须这么走、不这么走会翻车在哪、怎么一眼看出卡在哪一层。适合所有已安装 Git 但还没成功 push 过一次的人——哪怕你已经重装过三次 Git。

2. 本地 Git 初始化与首次提交：别跳过这三步检查，否则后面全是玄学

Git 不是“上传工具”，它是本地版本控制系统。上传（push）只是把本地已存在的提交（commit）同步到远程。所以第一步永远不是连 GitHub，而是让 Git 认出你的项目目录是“受管仓库”。很多人直接git add .就跑，结果发现.git目录没生成、git status报错“not a git repository”，根源就在这一步没立住。

2.1 创建本地仓库：git init的隐藏前提与验证方式

执行git init前，请确认当前终端路径是你代码所在的最外层文件夹（比如你的项目叫my-web-app，那路径必须是/path/to/my-web-app，而不是/path/to/或/path/to/my-web-app/src）。
运行命令：

git init

逻辑说明：该命令会在当前目录创建一个隐藏的.git文件夹，里面存着 Git 的元数据（对象库、分支指针、配置等）。它不联网，不依赖 GitHub，纯本地操作。
参数说明：无参数时初始化为默认仓库；加--bare会创建裸仓库（无工作区，仅用于服务器端接收 push，普通用户不用）；加--initial-branch=main可指定默认分支名（推荐，避免后续因master/main差异报错）。

验证是否成功：

• 执行ls -la（macOS/Linux）或dir /a .git（Windows），能看到.git文件夹；
• 执行git status，应返回On branch main（或master）和No commits yet；
• 若返回fatal: not a git repository (or any of the parent directories)，说明路径错了，用cd切到正确目录再试。

2.2 添加文件到暂存区：git add不是“选中文件”，而是“声明要纳入版本控制”

很多新手以为git add .是“把当前所有文件打包上传”，其实它只是把文件快照放进暂存区（staging area），为下一步commit做准备。Git 不跟踪空文件夹、不自动忽略编译产物，所以这一步必须主动干预。

先看当前有哪些未跟踪文件：

git status

你会看到类似：

Untracked files: (use "git add <file>..." to include in what will be committed) app.py requirements.txt __pycache__/

注意：__pycache__/被列为未跟踪文件——但你绝不想把它传到 GitHub（它是 Python 运行时生成的缓存，体积大且无意义）。此时必须先配置.gitignore。

创建并编辑.gitignore文件（用 VS Code、Notepad++ 或nano .gitignore）：

# Python __pycache__/ *.pyc *.pyo *.pyd .Python env/ venv/ .venv/ pip-log.txt # OS .DS_Store Thumbs.db # IDE .vscode/ .idea/

逻辑说明：.gitignore是 Git 的“过滤白名单”，它告诉 Git “这些路径下的文件，永远不要加入暂存区”。它只对尚未被 Git 跟踪的文件生效。如果__pycache__/已被git add过，.gitignore就失效了——必须先git rm -r --cached __pycache__/清除缓存。
参数说明：--cached表示只从 Git 索引中移除，不删除本地文件；-r递归处理文件夹。

保存后，再次运行git status，你会发现__pycache__/消失了，只剩真正需要版本控制的文件（如app.py,requirements.txt）。

现在执行添加：

git add app.py requirements.txt # 或一次性添加所有未忽略的文件 git add .

逻辑说明：git add .会递归扫描当前目录，把所有未被.gitignore排除、且未被 Git 跟踪的文件加入暂存区。它不会添加空文件夹，也不会添加已忽略的路径。
关键提示：如果你只想加部分文件（比如先传核心代码，文档稍后），用git add file1.py file2.js显式指定，避免误加调试日志或密钥文件。

2.3 提交到本地仓库：git commit是“打时间戳”，不是“上传”

暂存区准备好后，才能生成永久快照：

git commit -m "init: add core app files and requirements"

逻辑说明：git commit把暂存区的文件快照写入本地.git对象库，并创建一个唯一的 commit ID（如a1b2c3d）。这个操作完全离线，不接触网络。-m后的字符串是提交信息，必须写有意义的内容（不能是"update"或"fix"），因为它是你未来回溯代码变更的唯一线索。
参数说明：-m是 message 的缩写；若不加-m，Git 会打开默认编辑器（通常是 vim）让你输入多行信息；--amend可修改上一次提交（仅限未 push 前）；-a会自动add所有已跟踪文件的修改（但不会 add 新文件，慎用）。

验证提交是否成功：

git log --oneline

应输出类似：

a1b2c3d init: add core app files and requirements

至此，你的代码已在本地 Git 仓库中“落盘”，具备了可上传的基础。但注意：GitHub 上还没有任何东西，甚至还没有仓库。下一步才是连接远程。

3. 创建 GitHub 仓库与建立远程连接：HTTPS 和 SSH 不是二选一，是场景选择

很多人卡在git push报错，本质是没搞清：GitHub 仓库必须手动创建，Git 不会替你建；远程连接方式（HTTPS/SSH）决定了认证流程，选错等于自断后路。别急着复制粘贴 URL，先看清 GitHub 页面上的两个关键按钮。

3.1 在 GitHub 上创建空仓库：必须“空”且“同名”，否则 push 会拒绝

打开 github.com ，登录后点击右上角+→New repository。填写：

• Repository name: 必须和你本地项目文件夹名完全一致（比如本地是my-web-app，这里就填my-web-app）。虽然不强制，但名字不一致会导致后续git clone时路径混乱，新手极易混淆。
• Description: 随意写，不影响功能。
• Public/Private: 新手建议选Public（免费且可见），Private 需付费或用学生认证。
• Initialize this repository with a README?:务必取消勾选！

  原因：如果勾选，GitHub 会自动生成一个含README.md的 commit。而你的本地仓库是空的（只有你自己的app.py），git push时 Git 会发现“远程有 commit，本地没有”，拒绝推送（报错non-fast-forward）。你得先git pull合并，但新手根本不会处理冲突。所以——永远先建空仓库，再 push 本地内容。

点击Create repository。页面会跳转，显示一个空仓库，URL 类似https://github.com/yourname/my-web-app.git。

3.2 配置远程仓库地址：git remote add的 URL 格式决定认证方式

回到本地终端，确保你在项目根目录（my-web-app文件夹内），执行：

git remote add origin https://github.com/yourname/my-web-app.git

逻辑说明：git remote add是给远程仓库起一个本地别名（这里是origin），并绑定其 URL。origin是约定俗成的默认别名，几乎所有教程都用它。URL 中的https://表示使用 HTTPS 协议通信。
参数说明：origin是别名，可改成upstream或backup，但git push时需对应（如git push upstream main）；URL 必须和 GitHub 页面上显示的Clone with HTTPS地址完全一致（注意末尾的.git）。

提示：如果你看到 GitHub 页面显示Clone with SSH（以git@github.com:开头），那是 SSH 方式。它需要你提前生成 SSH 密钥并添加到 GitHub 账户（见 4.2 节）。新手强烈建议先用 HTTPS，因为它的错误信息更直白，排错成本低。

验证远程是否添加成功：

git remote -v

应输出：

origin https://github.com/yourname/my-web-app.git (fetch) origin https://github.com/yourname/my-web-app.git (push)

3.3 推送代码到远程：git push的分支映射是成败关键

现在执行推送：

git push -u origin main

逻辑说明：git push把本地分支的 commit 发送到远程仓库。-u（--set-upstream）是关键参数——它把本地main分支和远程origin/main分支永久关联。这样下次只需git push，Git 就知道推到哪。
参数说明：origin是远程别名；main是本地分支名。如果你的 Git 版本较老（<2.28），默认分支可能是master，则命令为git push -u origin master。如何确认？执行git branch，带*的就是当前分支。

如果一切顺利，你会看到类似输出：

Enumerating objects: 4, done. Counting objects: 100% (4/4), done. Writing objects: 100% (4/4), 352 bytes | 352.00 KiB/s, done. Total 4 (delta 0), reused 0 (delta 0) To https://github.com/yourname/my-web-app.git * [new branch] main -> main Branch 'main' set up to track remote branch 'main' from 'origin'.

刷新 GitHub 页面，你的app.py和requirements.txt就真实出现了。

注意：如果执行git push -u origin main报错error: src refspec main does not match any，说明你本地根本没有main分支（可能git init时没指定，或旧版 Git 默认master）。此时先查git branch，再用git checkout -b main创建并切换到main分支，再 push。

4. 认证失败排查：HTTPS 密码过期、SSH 密钥失效、Token 权限不足——三类高频翻车现场

90% 的git push失败不是网络问题，而是认证环节崩了。GitHub 已于 2021 年 8 月起全面禁用密码认证（即不能再输 GitHub 账号密码），必须用 Personal Access Token（PAT）或 SSH 密钥。下面按现象直击根因。

4.1 HTTPS 方式报Authentication failed：你还在输密码？

现象：执行git push后，终端弹出用户名/密码输入框，你输入 GitHub 账号和密码，报错Authentication failed for 'https://github.com/xxx/yyy.git/'。

原因：GitHub 已彻底废弃密码认证。你输入的密码无论对错，都会被拒绝。

解决：

1. 生成 Personal Access Token（PAT）：

   • 登录 GitHub → 右上角头像 →Settings→Developer settings→Personal access tokens→Tokens (classic)→Generate new token→Generate new token (classic)。
   • 勾选权限：至少选repo（读写私有/公开仓库）、delete_repo（删仓库，可选）、workflow（触发 Actions，可选）。
   • 点Generate token，立即复制生成的 token 字符串（形如ghp_abc123def456...），关闭页面——token 只显示一次！

2. 用 Token 替代密码：

   • 下次git push时，用户名输你的 GitHub 账号（如yourname），密码栏粘贴整个 token 字符串（不是密码！）。
   • 为免每次输入，配置 Git 缓存凭证：

     # macOS git config --global credential.helper osxkeychain # Windows git config --global credential.helper manager # Linux git config --global credential.helper cache

     首次输入 token 后，Git 会缓存它，后续 push 不再提示。

血泪经验：Token 权限别乱开。admin:org或delete_repo一旦泄露，攻击者能删你所有仓库。生产环境建议用 Fine-grained tokens（新式 Token），权限粒度更细。

4.2 SSH 方式报Permission denied (publickey)：密钥没配对或没加载

现象：用git@github.com:xxx/yyy.gitURL，执行git push报错Permission denied (publickey)。

原因：SSH 连接需公钥（存于 GitHub）和私钥（存于本地）严格匹配。常见原因：私钥文件权限过大、SSH agent 未启动、公钥未添加到 GitHub。

解决：

1. 检查私钥权限（Linux/macOS）：

   chmod 600 ~/.ssh/id_rsa

   如果权限是644或755，SSH 会拒绝读取，报错Bad permissions。

2. 启动 SSH agent 并添加私钥：

   eval "$(ssh-agent -s)" ssh-add ~/.ssh/id_rsa

   若提示Could not open a connection to your authentication agent，说明 agent 没启动。

3. 验证 SSH 连接：

   ssh -T git@github.com

   成功时返回Hi username! You've successfully authenticated...。失败则检查公钥是否已添加到 GitHub：Settings→SSH and GPG keys→New SSH key，粘贴cat ~/.ssh/id_rsa.pub的输出。

避坑：Windows 用户若用 Git Bash，确保ssh-agent已启用（任务栏右键 Git Bash 图标 →Options→Enable SSH Agent）；若用 PowerShell，需单独启动Start-Service ssh-agent。

4.3 其他认证相关报错速查表

5. 分支管理与持续上传：从main到dev，一次 push 不是终点

上传成功只是起点。真实开发中，你不会总在main分支改代码——那会污染主干。Git 的分支模型（Branching Model）是协作基石。本节教你用最小成本建立安全、可追溯的日常上传流。

5.1 创建开发分支：隔离新功能，保护main主干

假设你要开发一个新功能（比如增加用户登录），不要直接在main上改：

# 切换到 main，确保最新 git checkout main git pull origin main # 创建并切换到新分支 git checkout -b feature/login

逻辑说明：git checkout -b <branch-name>是git branch <branch-name>+git checkout <branch-name>的快捷组合。新分支feature/login会从当前main分支的 HEAD（最新 commit）开始分叉，独立演进。
命名规范：推荐type/description格式（如feature/xxx、fix/yyy、docs/zzz），便于团队识别意图；避免空格和特殊字符。

现在所有代码修改、git add、git commit都在feature/login分支进行。main分支保持干净，随时可发布。

5.2 同步远程分支：让队友看到你的进展

本地分支创建后，GitHub 上还不存在feature/login。需显式推送：

git push -u origin feature/login

逻辑说明：-u同样设置上游分支，之后在此分支上只需git push。GitHub 会自动创建同名远程分支。
关键区别：git push origin main是推送到已存在的远程main；git push -u origin feature/login是创建并推送新远程分支。

刷新 GitHub 页面，点击Branch: main下拉框，就能看到feature/login分支，以及你刚 push 的 commit。

5.3 合并到主干：Pull Request（PR）是协作的正式入口

功能开发完成，测试通过后，不能直接git merge到main。标准流程是发起 Pull Request（PR）：

1. 在 GitHub 仓库页面，点击Compare & pull request（通常在feature/login分支页顶部）；
2. 填写 PR 标题（如feat: add user login form）和描述（说明改动、影响、测试方法）；
3. 点Create pull request。

此时 PR 进入代码审查（Code Review）流程。团队成员可在 PR 中评论、要求修改、批准合并。只有批准后，才能点击Merge pull request，将feature/login的 commit 合并到main。

为什么不用git merge本地合并？
因为 PR 提供了审查、测试（可集成 CI）、讨论、审计日志的完整闭环。绕过 PR 直接 merge，等于放弃协作保障，是团队大忌。

合并后，本地需同步更新：

git checkout main git pull origin main # 拉取已合并的 commit git branch -d feature/login # 删除已合并的本地分支

注意：git branch -d只能删除已合并的分支；若要强制删除（如未合并），用git branch -D，但需谨慎。

6. 进阶技巧：用.gitconfig自动化重复操作，用git alias把长命令变短

当你重复执行git status、git add . && git commit -m "wip"、git push origin main时，说明该优化了。Git 的配置系统（.gitconfig）和别名（alias）能帮你省下每天 10 分钟——而且它们是跨项目的，一次配置，终身受益。

6.1 配置全局用户信息与默认行为：避免每次 commit 都被问“你是谁”

Git 要求每个 commit 记录作者信息。若未配置，git commit会报错please tell me who you are。在任意目录执行：

git config --global user.name "Your Name" git config --global user.email "your.email@example.com"

逻辑说明：--global表示写入全局配置文件（~/.gitconfig），对所有仓库生效；不加--global则只对当前仓库生效（写入.git/config）。
参数说明：user.name是显示名（非 GitHub 用户名）；user.email必须和 GitHub 账户绑定的邮箱一致，否则 commit 不会关联到你的 GitHub 账户头像。

进阶配置（写入~/.gitconfig）：

[core] editor = code --wait # 设置 VS Code 为默认编辑器（需安装 shell 命令） autocrlf = input # Windows 用户：提交时转 LF，检出时不转换（防换行符污染） [init] defaultBranch = main # 强制所有新仓库默认分支为 main（推荐） [pull] rebase = false # pull 时默认 merge（更直观），设 true 则变基

6.2 创建常用 Git 别名：把 5 个单词缩成 2 个字母

别名是提升效率的核武器。编辑~/.gitconfig，在[alias]段下添加：

[alias] # 状态简写 st = status -s # 日志美化（一行显示 commit id、作者、日期、信息） lg = log --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit # 一键添加+提交（慎用！确保你知道自己在提交什么） cm = "!f() { git add . && git commit -m \"$1\"; }; f" # 推送到当前分支（无需写 origin main） p = "!f() { git push origin $(git branch --show-current); }; f" # 拉取当前分支并 rebase（保持线性历史） up = "!f() { git pull --rebase origin $(git branch --show-current); }; f"

逻辑说明：cm是函数式别名，$1代表第一个参数（如git cm "add login ui"）；p和up用$(git branch --show-current)动态获取当前分支名，避免手误。
安全提示：cm别名虽快，但会git add .所有未忽略文件。我习惯用git add -p（交互式添加）逐块确认，再git commit -m，宁可慢一秒，不传错一行。

6.3 实用小技巧：三招快速定位上传问题

当git push卡住或失败，别盲目重试，按顺序查这三项：

1. 查网络连通性：

   ping github.com # 看是否能解析域名 curl -I https://github.com # 看 HTTPS 是否可达（返回 HTTP 200 或 302 即可）

2. 查 Git 状态与差异：

   git status -sb # -s 简洁模式，-b 显示分支 git diff --stat origin/main # 查看本地比远程多哪些修改（未 push 的 commit） git log origin/main..HEAD --oneline # 查看哪些 commit 还没 push 到远程 main

3. 查远程 URL 与凭证：

   git remote get-url origin # 确认 URL 是 https 还是 ssh git config --global credential.helper # 查看凭证助手是否启用 # macOS：钥匙串里搜 "github.com"，删掉旧凭据重试 # Windows：凭据管理器 → Windows 凭据 → 找 github.com 条目删除

最后说个我踩过的坑：某次在公司内网，git push总是超时。查了半天，发现是代理设置残留——执行git config --global --unset http.proxy和git config --global --unset https.proxy清除后立刻恢复。Git 的配置层级（系统/全局/本地）像洋葱，一层层剥，总有一层藏着问题。

希望帮到你。

本文还有配套的精品资源，点击获取