第一次把项目上传 GitHub：从文件检查到推送验收

这篇解决的是“把本地项目安全地放到自己的 GitHub 仓库”，不是所有网站必经的部署教程。Git 记录版本，GitHub 提供仓库托管与协作；上传代码后是否自动部署，取决于另一套项目设置。不会用终端时，也可以选择官方 GitHub Desktop 路线，步骤的检查目标相同。

先确认：你真的需要上传什么

只上传属于这个项目、你有权托管的源码和必要配置模板。生产密码、.env 私密配置、API密钥、客户文件、备份和日志不应混进去。依赖目录和构建产物是否提交按项目规则决定；不是看到一个大目录就全部添加。

以下命令示例面向已安装 Git 的终端环境。先在自己的项目目录执行；占位文件名、网址和分支必须替换成实际值，不照抄到服务器根目录。

第一步：已有仓库不要重新按新项目初始化

git status
git remote -v
git branch --show-current

如果能显示仓库状态，就先核对当前分支、未提交工作和远程地址。远程可能属于已有协作项目，不能擅自更换。只有确认这个项目尚未受 Git 管理时，才按官方新项目指引执行 git init -b main。遇到“not a git repository”先检查目录，不在任意目录反复初始化。

第二步：先检查文件，再建立一次提交

1. 列出本次需要版本化的文件，按项目要求设置忽略规则，保留无真实秘密的配置示例。
2. 明确添加已检查的文件，例如 git add README.md；将示例替换为实际文件。初次操作不要未经检查就添加整个目录。
3. 执行 git diff --cached --stat 查看范围，再执行 git diff --cached 检查内容。看到敏感文件就停止，不提交、不推送。
4. 执行 git commit -m "Describe this change"，将说明改成真实目的。提交成功后再查看 git status，区分已提交与未提交文件。

第三步：关联自己的空仓库并推送

在 GitHub 创建属于自己或获授权组织的仓库，先确认可见范围。新建远程若已有 README 等提交，就不能机械套用“空仓库”路线。已有远程则核对地址，不重复添加。

git remote add origin REMOTE-URL
git remote -v
git push -u origin main

这组示例仅适用于没有 origin、当前分支为 main 且远程为空的新项目。REMOTE-URL 使用仓库页面给出的地址；其他分支按实际情况处理。认证遵循 GitHub 当前官方支持方式，不把令牌写进命令示例、远程网址或截图。

常见卡点，不要靠强制覆盖解决

• 认证失败或权限拒绝：先核对账号、仓库归属和凭据权限，不公开凭据寻求帮助。
• 找不到分支或 refspec：检查当前分支及是否已经有提交，不为了消除报错随意改远程。
• non-fast-forward：远程存在本地没有的提交。停止推送，保存当前工作并查看差异；不会处理时请协作者帮助，不盲目 force push。
• 文件太大或推送中断：先确认哪个文件、是否该版本化及平台限制。不要反复把备份和依赖目录推上去。
• 已经提交过密钥：按官方建议先吊销或轮换暴露凭据，再评估历史和副本清理。仅删除文件或增加忽略规则不能撤销已经发生的泄露。

怎样确认上传完成

在仓库页面查看目标分支、最新提交和预期文件，确认可见范围正确。若绑定部署服务，再核对它实际部署的提交、构建状态和页面关键流程。仓库里出现文件只能证明上传，不证明登录、图片、接口或网站业务已经可用。

• 上传和部署前怎样处理密钥
• 代码推上去了，但页面白屏或报错怎么办

来源与核对范围

• GitHub：添加本地代码，支持新仓库初始化、远程关联和推送路线。
• GitHub：处理仓库敏感信息，支持先轮换凭据及历史清理边界。

折腾鸭编辑部于 2026-10-03 核对公开资料；命令为条件化示例，未替读者执行提交、推送或部署，不含推广链接。