前置教程 + 部署教程 - 杭州工作坊 #003

Step 1：用 AI 生成项目骨架（2 分钟）

对 AI 说：

                            请帮我用 Vite + React 创建一个 [你的创意] 项目，
包含首页、核心功能页面和基本样式。
要求：可以本地运行，代码结构清晰。
                        

运行：npm install && npm run dev，确认能跑起来。

Step 2：迭代核心功能（按需求时间）

黑客松技巧：

只做 1-2 个核心功能，不要贪多
每做一个功能就 git commit，避免出问题回退困难
用 AI 时说清楚"只改 X，不要动 Y"

Step 3：部署上线（3 分钟）

纯静态项目（推荐新手）：

推送代码到 GitHub
仓库 Settings → Pages → 选择分支 main 和目录 / 或 /dist
等 1-2 分钟，访问 https://<你的用户名>.github.io/<仓库名>/

💡 展示技巧：部署成功后把链接发到群里，比本地 demo 更有说服力！

前置教程

AI 编程工具速览与选型

把 AI 编程工具按用途分三类，你会更容易选对工具：

A. 对话式大模型（需求 → 方案 → 代码草案）

适合：拆需求、写 PRD、生成脚手架、解释报错、写测试、写文档
用法建议：把需求写成"可验收标准（Acceptance Criteria）"，让 AI 每次只改一小块

B. IDE 内助手（边写边补、边改边测）

适合：补全、重构、生成组件、按文件上下文修 bug
用法建议：让它"先给修改计划，再动手改"，并要求"改动点列表 + 回滚方式"

C. 终端/仓库级工具（批量重构、自动修复、多文件改动）

适合：跨文件重命名、批量加类型、自动生成/更新测试、升级依赖后的修复

黑客松里最实用的组合：对话式大模型（定方向）+ IDE 助手（落地）+ 测试。

Vibe Coding 入门：从"写代码"到"指挥代码"

Vibe Coding 的核心是：用自然语言描述需求，让 AI 生成代码，你负责验收与迭代。它强调"先做出能用的 MVP，再逐步完善"。

一个可落地的 Vibe Coding 工作流（强烈推荐照做）：

写清楚验收标准
- "打开首页能看到 X"
- "点击按钮 Y 会出现 Z"
让 AI 先输出方案与文件清单
- 例如：需要哪些页面/组件/接口/表结构/环境变量
- 明确数据流、路由、权限、部署方式
分小步生成代码
- 每次只让 AI 做一个模块，避免一口气要做个淘宝
本地跑起来
- 在本地运行 npm install && npm run dev
- 打开浏览器验证核心功能可用
- 检查控制台是否有报错
写最小测试/自测脚本
- 至少保证关键路径不挂（登录、下单、提交表单等）
- 可以用手动测试清单，或让 AI 帮你写简单的测试用例
推送到 Git，部署到线上
- git add . && git commit -m "feat: 完成 XX 功能"
- git push origin main
- 触发自动部署或手动在平台上部署

项目准备：仓库、分支、构建产物与基本规范

无论你用哪个部署平台，都建议按下面准备：

仓库必备

一个 Git 仓库（GitHub/GitLab/Gitee 任一）
明确默认分支：main 或 master
README 至少写：如何本地运行、如何构建、部署地址

构建必备

package.json 有明确脚本，例如：

dev：本地开发
build：生成部署产物
start：如为全栈/SSR（某些平台会用到）

产物目录要确认

Vite：常见 dist/
Next.js：可能是 SSR（不是纯静态目录）
文档站：可能是 docs/.vitepress/dist、build/ 等

GitHub Pages 部署教程（免费 / 静态站点最佳）

GitHub Pages 是什么 & 限制

GitHub Pages 是静态站点托管服务，从仓库获取 HTML/CSS/JS，（可选）通过构建过程处理后发布网站。

同时它也有明确限制（一定要知道）：

不适合用作"免费 Web 托管"来运营在线业务、电商或主要用于商业交易的网站
不应处理敏感事务（比如发送密码/信用卡号）
仓库建议上限 1GB，发布站点 ≤ 1GB
部署超过 10 分钟会超时
带宽软限制 100GB/月
生成次数软限制 10 次/小时

一句话：GitHub Pages = 纯静态内容展示非常强；但不要把它当"后端服务器"。

从分支部署（最简单）

操作步骤：

确保发布源分支存在（例如 main）
进入仓库 Settings
左侧 Pages
"Build and deployment" → Source 选择 Deploy from a branch
选择分支 + 文件夹（根目录 / 或 /docs）
Save

使用 GitHub Actions 自定义工作流部署（适配各种框架）

当你用 Vite/React/Vue/Docusaurus 等需要构建的框架时，推荐用 Actions。

一个通用工作流示例（可直接改）

把下面文件放到：.github/workflows/pages.yml

                        name: Deploy to GitHub Pages

on:
  push:
    branches: [ "main" ]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v5

      - name: Setup Pages
        uses: actions/configure-pages@v5

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "npm"

      - name: Install
        run: npm ci

      - name: Build
        run: npm run build

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v4
        with:
          path: dist   # 改成你的输出目录

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy
        id: deployment
        uses: actions/deploy-pages@v4
                    

HTTPS 与自定义域名要点

GitHub Pages 支持开启 HTTPS，并提供"强制 HTTPS"的选项。

常见做法：

子域名（例如 www.example.com）：DNS 配 CNAME 指向你的 <owner>.github.io
根域名（例如 example.com）：通常配 A 记录（按 GitHub 文档给的 IP）

附录

Vibe Coding 常用提示词模板（可复制）

模板 1：需求 → 任务拆分

                        你是资深全栈工程师。请把下面需求拆成最小可交付任务列表
                    

模板 2：只改一件事

                        只做"X 功能"，不要顺带重构。给出代码差异（或完整文件）。
                    

模板 3：部署排障

                        我在 GitHub Pages 部署失败，构建日志如下：……
请给我 3-5 个候选排查方式，并告诉我优先排查顺序。
                    

上线前检查清单

静态站（GitHub Pages）

✅ npm run build 本地可成功
✅ 输出目录里有 index.html
✅ 站点内资源路径正确（尤其是带仓库名的 base path）
✅ README 写清楚构建与部署方式

前置教程 + 部署教程（GitHub Pages）

目录

5 分钟快速开始