前置教程 + 部署教程 - 北京工作坊 #001

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/<仓库名>/

需要 API/后端功能：

使用 EdgeOne Pages（支持 Node.js 函数）
参考下方 EdgeOne Pages 部署指南

💡 展示技巧：部署成功后把链接发到群里，比本地 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/ 等

部署方案选择：EdgeOne Pages vs GitHub Pages

先用一句话分清：

GitHub Pages：静态站点托管服务，从仓库拿 HTML/CSS/JS（可选构建）并发布
EdgeOne Pages：基于 Tencent EdgeOne 的现代 Web 开发/部署平台，支持静态站点与无服务器应用，并可通过边缘函数扩展动态能力

怎么选（最常用决策）

你做的是纯静态站（博客/文档/活动页/作品集）→ GitHub Pages
你需要API、鉴权、WebSocket、SSR/动态功能 → EdgeOne Pages（更省事）
你特别在意国内访问体验/需要按"加速区域"考虑备案 → EdgeOne Pages

EdgeOne Pages 部署教程（国内可用 / 支持全栈）

适用范围与核心概念

EdgeOne Pages 常见用法：

导入 Git 仓库一键部署（推荐）
从模板开始快速跑通 Demo
直接上传构建产物（适合你在本地/别的 CI 已构建好）

通过导入 Git 仓库部署（推荐）

Step 0：准备仓库

确保仓库能在本地正常 install → build
确认构建命令（例如 npm run build）和输出目录（例如 dist）

Step 1：连接 Git 提供商

Pages 支持 GitHub / GitLab / Gitee 等接入。

操作路径（以 GitHub 为例）：

登录控制台后，选择"导入 Git 仓库"
绑定/授权 GitHub（授予仓库访问权限）
选择要部署的仓库（或授权全部仓库）

Step 2：填写构建配置并开始部署

选择仓库
填写构建命令（不确定就看 package.json scripts）
选择加速区域（会影响节点资源 & 自定义域名备案要求）
点击"开始部署"，平台会自动构建并部署到边缘网络

Step 3：自动持续部署（CI/CD）

当新的提交推送到部署分支时，平台会自动拉取并部署最新提交。

构建设置：根目录、构建命令、输出目录、Node 版本

在 Pages 的构建指南里，关键点是这几个：

根目录：构建命令在哪个目录执行（默认仓库根目录 ./）
输出目录：构建产物目录（相对根目录）
构建命令：例如 npm run build，在 Bash 中运行
安装命令：平台会根据 lock 文件自动检测（npm/yarn/pnpm）
Node 版本：平台预装多个 Node 版本，可在项目设置里选择

经验法则：90% 的部署失败都来自"输出目录填错"或"根目录填错"。

不确定时：本地 npm run build 后看产物到底落在哪个文件夹。

环境变量：添加、批量导入与生效规则

Pages 支持环境变量，并说明了两条非常重要的规则：

可以把 .env 的内容整段粘贴到变量名输入框，平台会自动识别并批量导入
环境变量的更改不会影响历史部署，只对新的部署生效

Node Functions：在同一仓库写 API / WebSocket

如果你需要"全栈"（接口、鉴权、WebSocket），用 Node Functions 最顺手。

能做什么

Node Functions 提供 Node.js 运行时，可处理 HTTP 请求，也支持 WebSocket 双向通信。

最小示例：一个 hello API

在仓库创建文件：

                        // 文件路径：./node-functions/api/hello.js
// 访问路径：example.com/api/hello
export default function onRequest(context) {
  return new Response("Hello from Node Functions!");
}
                    

本地调试

官方给的方式是：

全局安装 CLI：npm install -g edgeone
在项目目录运行：edgeone pages dev 启动本地调试

使用限制（上线前一定要看）

文档列出了关键限制：

代码包大小：128 MB
请求 body：6 MB
单次运行时长：30s
开发语言：Node，默认 Node.js v20.x

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：部署排障

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

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

目录

5 分钟快速开始