造物栈

Method

GitHub 提交与部署准备流程：把本地项目整理成可提交、可部署的状态

本地项目能 build 通过，不代表已经适合提交和部署。提交前要确认 Git 仓库、.gitignore、敏感文件、构建目录、部署参数和 README，避免把 node_modules、dist、备份文件或密钥一起交出去。

方法解决什么问题

很多人本地项目能正常运行后，就直接尝试连接 GitHub 和部署平台，然后遇到各种问题：不知道应该在哪个目录执行 git init、在 apps/web 里初始化仓库导致根目录文档没进仓库、忘记 .gitignore 把 node_modules 和 dist 提交进去、不知道部署平台 Root Directory 应该填 apps/web、GitHub 新建仓库时勾选 README 导致冲突。提交和部署准备流程的作用，是在真正连接外部平台之前，先把本地项目整理到安全、干净、可提交的状态。

适合谁

  • 静态内容站（Astro / Next / Vite / Hugo 等）
  • 本地文件驱动的网站
  • 准备连接 GitHub 的个人项目
  • 准备部署到 Vercel / Cloudflare Pages / Netlify 的项目
  • 造物栈这种 first content, then system 的项目
  • 初次 Git 提交前的整理检查

不适合谁

  • 大型企业发布流程
  • 多环境 CI/CD
  • 数据库迁移
  • 多人权限审批
  • 高并发后端服务

提交与部署准备八个步骤

  1. 第 1 步：确认项目根目录

    确认当前项目根目录是 C:\ZaowuZhan，而真正的前端应用目录是 apps/web。package.json 在 apps/web 里，不在根目录。如果你在 apps/web 里初始化 Git 仓库，根目录的 README、AGENTS.md、PROJECT_STATUS.md 和 docs 都不会被纳入版本管理。

  2. 第 2 步：确认构建通过

    先运行 build，确认当前项目处于可提交状态。如果 build 报错，先修复问题再考虑提交——不要把有构建错误的状态提交到仓库。build 后的静态页面数量和 sitemap URL 数量也应与预期一致。

  3. 第 3 步：检查 .gitignore

    确认 .gitignore 已覆盖 node_modules、dist、.astro、.env、*.log、file_backups、旧备份目录和临时文件。没有 .gitignore 的 Git 仓库极其危险——一次 git add . 就可能把几百 MB 的 node_modules 提交进去。

  4. 第 4 步：检查敏感文件

    确认没有 API key、token、secret、credentials 或 .env 文件会被提交。敏感文件一旦进入 Git 历史，即使后续删除，仍然可以通过 git log 找回。如果有敏感文件，先加入 .gitignore，再考虑是否需要用 git rm --cached 清理。

  5. 第 5 步：初始化 Git 仓库

    在项目根目录（C:\ZaowuZhan）执行 git init，而不是在 apps/web 或 C:\Users\AS。初始化后立即检查 git status，确认 .gitignore 生效、不该提交的文件确实被忽略。

  6. 第 6 步：首次提交

    先 git status 看清楚要提交什么，再 git add . 和 git commit。首次提交信息建议写清楚项目名称和状态，例如「初始化造物栈静态内容站」。不要在这个时候提交太细碎的文件改动。

  7. 第 7 步：连接 GitHub

    在 GitHub 创建远程仓库（建议先设为 private），绑定 origin，推送 main 分支。注意：新建 GitHub 仓库时不要勾选 README 和 .gitignore 模板，否则会与本地文件冲突，需要先 pull 再 merge。

  8. 第 8 步：准备部署平台参数

    记录 Root Directory=apps/web、Build Command=npm run build、Output Directory=dist、Install Command=npm install、Node.js >=22.12.0。这些参数在连接 Vercel / Cloudflare Pages / Netlify 时都需要填写。不要把 Root Directory 设置成项目根目录，否则平台可能找不到 package.json。

一个真实场景示例

以造物栈从本地项目推进到可提交状态为例，提交与部署准备流程是这样走通的：

走完这 8 步，本地项目就从「只有自己能跑」变成了「可以安全提交给 GitHub、可以连接部署平台」的干净状态。

提交前最低检查清单

在 git add 和 git commit 之前，逐项确认：

  1. 项目根目录是否正确

    在 C:\ZaowuZhan 而非 apps/web 或用户目录初始化 Git。

  2. 构建是否通过

    npm run build 无报错，静态页面和 sitemap 数量正常。

  3. .gitignore 是否存在

    已覆盖 node_modules、dist、.astro、.env、file_backups、日志。

  4. 敏感文件是否已排除

    无 .env、API key、token、secret、credentials 进入暂存区。

  5. node_modules 是否已被忽略

    git status 中不应出现 node_modules 目录。

  6. dist 是否已被忽略

    git status 中不应出现 dist 目录。

  7. 部署参数是否已记录

    Root Directory、Build Command、Output Directory 已写清楚。

  8. README 是否已说明启动方式

    避免部署平台或协作者找不到正确的启动命令。

提交与部署前最低检查对象

以下对象在 git add 前都应纳入检查范围：

目录与文件

  • 当前目录（确认在项目根目录，而非 apps/web 或用户目录）
  • Git 仓库状态（git status）
  • .gitignore（是否覆盖关键忽略项）
  • package.json 位置（在 apps/web，不在根目录）
  • README（是否已说明正确的启动和构建命令）
  • PROJECT_STATUS（是否已记录最新状态）

不应提交的内容

  • node_modules
  • dist
  • .env / API key / token / secret
  • file_backups
  • 日志文件
  • 临时截图或无关文件
  • 旧备份页面目录

常见错误

目录与初始化错误

  • 在 C:\Users\AS 执行 git init
  • 在 apps/web 里初始化仓库，导致根目录文档没进仓库
  • GitHub 新建仓库时勾选 README / .gitignore 导致冲突
  • 部署平台 Root Directory 填成项目根目录而不是 apps/web

提交与部署后疏漏

  • 忘记 .gitignore，把 node_modules 或 dist 提交进去
  • 把 .env 或 API key 提交到公开仓库
  • 把 file_backups 和旧备份页面提交进去
  • 部署成功就以为完成，不做上线后检查

常见错误

  • 在 C:\Users\AS 执行 git init，完全搞错目录
  • 在 apps/web 执行 git init，根目录文档丢失
  • 忘记 .gitignore，node_modules 被提交
  • 把 dist 提交进仓库
  • 把 .env 或 API key 提交进仓库
  • GitHub 新建仓库时勾选 README 导致冲突
  • 部署平台 Root Directory 填错，找不到 package.json
  • 只部署成功，不做上线后检查

最低命令清单（用户自行按阶段执行）

  1. cd C:\ZaowuZhan（确认在项目根目录）
  2. git init（初始化 Git 仓库）
  3. git status（确认哪些文件会被提交，哪些被忽略）
  4. git add .（添加所有文件，确认无敏感内容）
  5. git commit -m "初始化造物栈静态内容站"
  6. 在 GitHub 创建仓库（不勾选 README 和 .gitignore）
  7. git remote add origin https://github.com/<你的用户名>/<仓库名>.git
  8. git branch -M main && git push -u origin main
  9. 在部署平台填写 Root Directory=apps/web, Build Command=npm run build, Output Directory=dist

相关模板

项目状态检查模板基础版项目进度记录模板基础版Codex 验收清单模板基础版文章发布 SOP 模板基础版长期开发保障方案模板基础版

相关内容

本地发布流程上线后检查流程项目状态检查不要让内部文档进入公开路由不要只看首页就认为网站正常不要在疲劳状态下做大重构不要写完 Markdown 就直接发布

使用路径 · 第 7 / 8 步

这套方法在流程中的位置

你现在看到的是造物栈 AI 项目实战流程的第 7 步： GitHub 提交与部署准备流程。把本地项目整理成可安全提交、可交给部署平台的干净状态。

  1. 1 工具雷达四问
  2. 2 绿色 / 黄色 / 红色任务分级
  3. 3 Codex 协作流程
  4. 4 项目状态检查
  5. 5 内容生产流程
  6. 6 本地发布流程
  7. 7 GitHub 提交与部署准备流程
  8. 8 上线后检查流程
上一步 本地发布流程 下一步 上线后检查流程

下一步怎么用

先不要追求自动化 CI/CD。第一阶段只要确保：本地 build 通过、仓库提交干净、部署参数正确、上线后检查完整，就已经足够。提交不是结束，而是把本地项目安全交给部署平台的第一步。

返回方法栈