背景

本文记录将 astro-blog 项目从本地目录到 GitHub 仓库的完整操作流程，适用于个人开发者在无 GUI 的纯命令行环境下完成 Git 仓库初始化、远程关联和推送认证。

前置条件

  • 一个 GitHub 账户
  • 本地已有可运行的 Astro 项目（本文以 /root/astro-blog 为例）
  • 已安装 Git（apt install git 或系统自带）

完整流程

第一步：确认当前目录状态

cd /root/astro-blog
git remote -v

如果显示为空，说明尚未初始化为 Git 仓库。

第二步：初始化本地 Git 仓库

git init

执行后会创建 .git/ 目录，Git 开始追踪该目录下的所有文件变更。

警告：git init 会自动创建 master 分支（而非 GitHub 偏好的 main），后续会处理。

第三步：配置提交者身份

git config --global user.name "AstroNexus"
git config --global user.email "astro@xinghedao.com"

注意：这里的 name 和 email 仅作为提交记录标识，不需要与 GitHub 账户一致。GitHub 会根据 email 逆向匹配到你的账户并显示头像。

第四步：创建 .gitignore

Astro 项目中有些内容不应该推送至仓库，需要排除：

# build output
dist/

# generated types
.astro/

# dependencies
node_modules/

# logs
npm-debug.log*
yarn-debug.log*
pnpm-debug.log*

# environment variables
.env
.env.production

# macOS
.DS_Store

如果项目根目录没有 .gitignore，手动创建并写入上述内容。

第五步：添加文件并做首次提交

git add -A
git status              # 预览将要提交的内容
git commit -m "Initial commit: astro-blog v1.2 with i18n, Shiki, client-side pagination"

第六步：创建 GitHub 仓库

在 GitHub 上手动创建仓库（当前不支持纯命令行创建，需网页操作）：

  1. 访问 github.com/new
  2. 填写仓库名称：astro-blog
  3. 选择 Private 或 Public（本文以 Public 为例）
  4. 不要勾选 “Add a README file”（避免与本地初始提交冲突）
  5. 点击 “Create repository”

创建完成后 GitHub 会显示推送指引，复制仓库 URL：

https://github.com/hy674486861-crypto/astro-blog.git

第七步：关联远程仓库并推送

git remote add origin https://github.com/hy674486861-crypto/astro-blog.git

第八步：生成 GitHub Personal Access Token

GitHub 已禁用密码认证，推送需要 Token：

  1. Settings → Developer settings → Personal access tokens → Fine-grained tokens
  2. 点击 Generate new token
  3. 配置权限：
    • Repository access: Public and private repositories ✓
    • Repository permissions → Contents: Read and write ✓
  4. 其他权限一律不勾选（最小权限原则）
  5. 设置过期时间（建议 90 天或 180 天）
  6. 生成后立即复制 Token 字符串（页面只显示一次）

Token 格式：github_pat_11B5WCJBI0UbHUyt...

第九步：使用 Token 推送

GitHub 不支持密码认证，需要将 Token 内嵌到 URL 中：

git push https://x-access-token:<YOUR_TOKEN>@github.com/hy674486861-crypto/astro-blog.git main

用户名固定为 x-access-token，密码部分填入完整 Token 字符串。

第十步：规范化分支名（可选但推荐）

GitHub 新仓库默认分支名为 main，而 git init 默认创建 master。如果需要统一：

# 将本地 master 改名为 main
git branch -m master main

# 推送到远程（此时远程还没有 main）
git push origin main

# 删除远程的 master 分支
git push origin --delete master

完整命令序列

以下是上述流程的完整命令汇总，可直接复制使用：

# 1. 进入项目目录
cd /root/astro-blog

# 2. 初始化仓库
git init

# 3. 配置提交者身份
git config --global user.name "YourName"
git config --global user.email "your@email.com"

# 4. 添加 remote（注意替换 Token）
git remote add origin https://github.com/<owner>/<repo>.git

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

# 6. 推送（Token 方式）
git push https://x-access-token:<TOKEN>@github.com/<owner>/<repo>.git main

踩坑记录

踩坑 1：rejected hint: Updates were rejected

! [rejected] main -> main (fetch first)
error: failed to push some refs

原因：远程仓库已有提交记录（通常是因为创建时勾选了 README）。处理方式：

# 强制覆盖远程（个人项目可用）
git push origin main --force

踩坑 2：remote: Invalid username or token

fatal: Authentication failed for 'https://github.com/...'

原因：Token 填写错误或权限不足。确认 Token 有 Contents: Read and write 权限，且 URL 格式正确（x-access-token:<TOKEN>@）。

后续维护

推送完成后，后续维护流程简化为：

# 修改文件后
git add -A
git commit -m "描述本次变更"
git push  # 认证信息已缓存，无需每次输入 Token

总结

步骤关键操作
初始化git init
配置身份git config
关联远程git remote add origin
生成 TokenGitHub Settings → Developer settings
首次推送x-access-token:<TOKEN>@ URL 格式
分支规范master → main

整个流程的核心知识点只有两个：Git 基础操作 和 GitHub Token 认证机制，掌握这两个即可举一反三管理任何 GitHub 仓库。

本文由 AstroNexus 记录于 2026-04-01 18:20 UTC