更多内容请访问我的个人网站
约 12 分钟读完;需要你会命令行、知道静态网站是什么;不懂 React 也能跟。
读者是谁
这篇讲一个人从零把一个静态站做到上线,下面按角色列出你能带走什么、从哪节开始读。
| 读者 | 带走什么 | 拿它做什么 | 从哪节开始读 |
|---|---|---|---|
| 会写 React/JS 但没部署过静态站的前端 | 选型对比表 + 构建期预渲染方案 | 照第 4、5、7、8 节把自己的站从空壳做到能被搜到 | 4 → 8 |
| 想用 AI 结对开发的独立开发者 | 14 项 SEO 自动检查清单 + EdgeOne 那 2 条规则 | 直接抄成自己项目的检查脚本 | 5 → 8 |
| 要给自己搭作品集的学生 | 8 个页面骨架 + 视觉反模式清单 | 先抄结构,再换自己的内容 | 2 → 4 |
| 手里有旧博客要搬过来的人 | 旧文迁移的字段映射表 + 三个坑 | 照第 6 节写自己的导入脚本 | 6 |
只想学 React 语法、不打算部署的人不必读------这里讲的是从零到上线的决策与坑。
0 本文讲什么
这篇讲我用 AI 从零做一个个人网站的第一版全貌:先定「给谁看、看完做什么」,再定视觉规则和技术栈,然后搭 8 个页面、做 SEO、搬 271 篇旧文,最后是域名、不备案方案和上线首日踩的坑。读它你能带走选型对比表、视觉反模式清单、EdgeOne 的 2 条规则和坑对照表。
先看这张表,决定要不要继续读:
| 小节 | 讲什么 | 读它能得到什么 |
|---|---|---|
| 1 | 定位:博客还是名片 | 先想清访客与转化目标 |
| 2 | 视觉规范(颜色/字体/禁止事项) | 一份可验收的样式规则 |
| 3 | 技术选型:为什么不用 Next.js | 选型对比表 |
| 4 | 环境准备与最小可跑示例 | 一条能跑通的命令 |
| 5 | SEO 基建:预渲染/站点地图/14 项检查 | 静态站的 SEO 清单 |
| 6 | 271 篇旧文迁移 | 迁移时的三个坑 |
| 7 | 域名与不备案方案 | 加速区域选择表 |
| 8 | EdgeOne 回源与网址(URL)重写 | 2 条最终规则 |
| 9--10 | 上线首日坑、下一步动作 | 排查对照表 |
1 定位:做博客还是做名片
先定这一节,是因为定位决定页面结构和视觉;定位含糊,后面每个页面都会摇摆。三类常见做法:纯博客(内容主角是文章列表,访客读完就走)、纯名片(一页介绍加联系方式)、档案站(作品、文章、履历互相印证,让访客判断能力边界并发起合作)。选档案站:陌生访客判断不了能力边界、作品散落在多个平台、联系方式藏在角落,三个痛点它都能解。落地成 8 个页面:首页、关于我、作品集、作品详情、博客列表、文章详情、服务与报价、联系,每个页面对应访客的一个问题。中英双语按浏览器语言自动切换,手动选择存 localStorage(浏览器本地存储)。
2 视觉规范:把「好看」变成可验收的规则
需要这一节,是因为「好看」主观,验收时容易各说各话;把规则写死,改样式才有唯一标准。色板只留三个角色:底色 #fafaf9、正文 #18181b、强调色 #2563eb;强调色只用于主按钮、当前导航下划线、链接 hover;禁第二强调色、禁大面积渐变、颜色一律走 CSS 变量。下面这段是色板的唯一来源,组件只引用变量、不写死色值:
scss
:root {
--bg: #fafaf9;
--text: #18181b;
--border: #e4e4e7;
--accent: #2563eb;
--accent-hover: #1d4ed8;
}
字体用系统无衬线加等宽;正文行高 1.75、行长 68ch,中文不加正 letter-spacing,最多三级标题。最常犯的五条反模式:emoji 当图标、文字阴影发光、所有区块居中、卡片塞三段以上、移动端横向滚动。验收做成可执行:三个视口截图(1440×900 / 768×1024 / 390×844)+ 移动端断言 scrollWidth ≤ innerWidth + 1 + 扫源码确认 #1677ff、emoji、内联 color 命中数为 0。
3 技术选型:为什么是 React + webpack + CloudBase
选型决定 SEO 能不能做,先交代托管方式的领域前提:CloudBase(腾讯云的云开发,把构建产物按文件传上去、由平台域名对外提供访问,第 7 节细讲)的静态托管只发构建产物(HTML/JS/CSS),没有 Node 运行时;请求按路径映射文件,/projects 找 /projects/index.html。在这个前提下比较:
| 选项 | 怎么工作 | 问题 |
|---|---|---|
| A Next.js | 服务端渲染(SSR)/静态生成,SSR 需要 Node 运行时 | 静态托管没有 Node,SSR 跑不起来 |
| B 纯单页应用(SPA) | 一个 index.html,浏览器里渲染全部页面 | 搜索引擎只拿到空壳 |
| C SPA + 构建期预渲染 | 构建时把每个路由生成静态 HTML,托管仍是纯静态 | 需要自己写预渲染脚本(选它) |
选 C,约束是跟论坛同栈(React 18 + webpack 5 + CloudBase 静态托管):A 被托管形态排除,B 的 SEO 只有空壳,C 兼顾两者。构建产物 287 个页面 = 271 篇文章 + 8 个作品 + 8 个静态页(来源:构建后的 routes.json 条数)。
4 环境准备与最小可跑示例
先把骨架跑通,才有一切可谈。环境:Node 18+ 与 yarn;在 packages/personal-site 下装依赖,再按固定顺序构建和自检:
bash
yarn install
yarn webpack
node scripts/check-seo.mjs
构建完成后,下面这段脚本能立刻验证「预渲染是不是真的生成了页面」:它扫描 dist 下所有 index.html,数页面数并找出重复标题(20 行,复制即可跑):
node
const fs = require('fs');
const path = require('path');
const pages = [];
function walk(dir) {
for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
const full = path.join(dir, entry.name);
if (entry.isDirectory()) walk(full);
else if (entry.name === 'index.html') pages.push(full);
}
}
walk('dist');
const titles = new Map();
for (const file of pages) {
const match = /<title>([^<]*)<\/title>/.exec(fs.readFileSync(file, 'utf8'));
const key = match ? match[1].trim() : '(missing)';
titles.set(key, (titles.get(key) || 0) + 1);
}
console.log('页面数:', pages.length);
console.log('重复标题:', [...titles].filter(([, n]) => n > 1).length);
日常更新就是重跑上面三条命令、上传 dist、再刷新内容分发网络(CDN)的缓存。怎么读结果:页面数应等于路由数(这台 287);重复标题数应为 0。代码第 5 行的 walk() 递归收集页面,第 13 行的 Map 统计重复标题。
5 SEO 基建:让静态站也能被搜到
需要这一节,因为 SPA 的 HTML 是空壳,搜索引擎拿不到标题和正文。三个概念先说清:预渲染=构建时把每个路由渲染成静态 HTML(保留 #root 供浏览器接管);sitemap=给搜索引擎的页面清单;结构化数据=用 JSON-LD(搜索引擎认的格式)描述「这人是谁、这篇是什么」。
预渲染有两条路,都能把 HTML 变厚:
| 方案 | 做法 | 代价 |
|---|---|---|
| A 无头浏览器逐页渲染 | 起 271 次 Chrome,等页面渲染完再存 HTML | 慢,且容易「假绿」(检查显示通过、其实没生效) |
| B 模板注入 | 用同一份内容数据把 <head> 拼进模板 |
快,正文仍由浏览器渲染 |
第一版走 A:跑 271 次 Chrome,产物 body 里 article 标签 0 个、正文关键词 0 次,383 秒只换来 30KB 的 head。改 B 后 383 秒降到 64 秒。为什么选 B:SEO 要的是 head 和元信息,正文交给浏览器;逐页跑浏览器的成本高且难验证。
再配 14 项自动检查(check-seo.mjs 逐项 record,跑完打印 14/14):标题唯一、canonical(页面唯一地址)绝对地址、hreflang(多语言版本指向)三档、h1 唯一、JSON-LD 可解析、og:image(分享预览图)存在、sitemap 条数与库内已发布数对账。最后一条防「凭据过期后静默降级成种子数据,检查却全绿」。
6 内容迁移:271 篇旧文怎么搬
空站没有内容,先把历史资产搬进来,从「东西从哪来」讲起。
这 271 篇从哪来 :早年写在博客园的文章,导出成 markdown 放在本地 D:/Github/MyData/blog/ 下;另一部分是灵性资料,在 MyData/karma/ 下,外加三篇顶层文件(《分享我收集的灵性灵修资源》等)。
数据长什么样 :文件名形如 2013-09-27-Javascript设计模式之我见-观察者模式.md,即「日期-标题」;正文是 markdown;没有任何结构化字段------没有 tags(标签,用来分类和筛选,本站约定只用 1 个)、没有 summary(摘要,列表页卡片和搜索结果里显示的那段话)、没有 slug(网址里那串标识,决定这篇文章的访问地址,例如 /blog/2026-11-15-用-AI-...)。下面这张表是源文件与数据库字段的映射:
| 源文件里有什么 | 库里需要什么 | 怎么映射 |
|---|---|---|
文件名 2013-09-27-标题.md |
publishedAt(发布时间)+ title |
在第一个 - 处切:前半日期,后半标题 |
| 正文 markdown | content |
原样存入 |
| 没有 tags | tags(每篇 1 个) |
blog 目录按标题和正文做关键词分析;karma 固定「灵性资料」 |
| 没有 summary | summary(≤155 字) |
取正文首段,超长截断并补省略号 |
| 没有 slug | slug(页面地址) |
由标题生成:保留中文、去标点,前面加日期 |
脚本按这个顺序做:扫描 blog / karma / 顶层三个来源 → 从文件名切出日期与标题 → 取正文首段生成 summary(≤155 字)→ 按来源目录打标签 → 由标题生成 slug(保留中文、去标点,并过滤 Windows 非法字符)→ 写入云数据库的两个集合(一份给构建读、一份给线上读)。先 dry-run 看统计与样例,确认后再写库:
bash
# 先 dry 看统计与样例,确认无误后再 write
node scripts/import-mydata.cjs --dry
node scripts/import-mydata.cjs --write
三个坑,下面按「是什么 → 为什么是坑 → 怎么解决 → 为什么能解决」列出来:
| 坑是什么 | 为什么是坑 | 如何解决 | 为什么能解决 |
|---|---|---|---|
| slug 生成后又改了标题 | 旧链接和搜索结果里的地址会 404 | 冻结 slug:生成后不再随标题变 | 地址是对外契约(对外的承诺),内容可以改、地址不该改 |
| 正文里还有原站的图片外链 | 换域名后被防盗链拦掉,图片全裂 | 图片本地化上传到云存储,或给 img 加 referrerPolicy="no-referrer" |
不带 Referer 头,就不触发防盗链的来路判断 |
| 重复导入同一批文件 | 要么写出重复文章,要么覆盖掉手工改动 | 按 slug 命中就跳过;或导入前清空目标集合(本脚本 --write 是后者,别在有手工改动时重跑) |
幂等键唯一 + 破坏性开关明确写出来 |
7 域名与不备案:yangyuanchao.cn
先把两个平台介绍清楚,后面的操作才看得懂。
CloudBase(腾讯云的云开发)是一套无服务器云服务:不用买服务器、不用自己配 Nginx(Web 服务器软件),把构建产物按文件传上去,平台就给一个域名对外提供访问,还自带数据库、云函数(按需运行的代码)、文件存储。这个站的前端文件、文章数据(存在云数据库的两个集合里)以及评论和统计云函数都跑在它上面。选它的原因:跟论坛同一套栈、免费额度够用、不需要运维。
部署完之后,CloudBase 只给你一个平台域名 xxx.tcloudbaseapp.com(源站,真正放着 dist 文件的地方)。要让访客用 yangyuanchao.cn 打开,中间要串起三样东西:域名 → CDN → 源站。这里的 CDN 用 EdgeOne(腾讯云边缘安全加速平台):把文件缓存到全球节点、访客就近取,还提供免费的超文本传输安全协议(HTTPS)证书、缓存刷新、URL 重写规则;选它是因为这套配置我已经完整跑通过一遍:gts-play.cn 是我另一款游戏项目的官网,同样架在 CloudBase + EdgeOne 上、同样没备案;另外它不备案也能绑自有域名、免费额度够。下面按五个问题拆开讲。
7.1 为什么要域名
平台域名又长又像测试地址,不能换 CDN、不利于传播。自有域名才能承载 SEO 的品牌信号(canonical 和站点名用的都是它),也能在换托管商时保住地址------书签和搜索结果不会断。域名是门牌,托管商是仓库:仓库可以搬,门牌最好不变。
7.2 源站 *.tcloudbaseapp.com 是什么
这是 CloudBase 静态托管开通后分配的默认访问域名,指向你上传的 dist。它一直都在,自有域名只是「更好看的入口」,两者是「门牌 vs 后台仓库」的关系:仓库地址不变,访客只认门牌。
7.3 域名怎么注册的
在腾讯云 DNSPod 买 yangyuanchao.cn(.cn 按年付费,价格以后台为准)。注册完做两件事:实名认证(.cn 强制),以及解析------加一条别名记录(CNAME)指向 EdgeOne 分配的加速域名,访问才会先到 CDN。
7.4 怎么做到「不备案又绑域名」
备案是「域名解析到中国大陆境内的服务器」才需要的。在 EdgeOne 控制台把加速区域改到「站点 → 加速区域 → 全球(不含中国大陆)」,请求不落在境内节点,就不触发备案要求,所以不备案也能绑自有域名。代价要写清:国内访问绕道境外节点、首屏变慢;选了不含大陆的区域,就不能用大陆节点,想加速国内只能重新备案。下面这张表对比两个区域的备案要求与代价:
| 加速区域 | 是否要备案 | 代价 / 结论 |
|---|---|---|
| 中国大陆 | 必须 | 多几周备案周期;国内访问最快 |
| 全球(不含中国大陆) | 不需要 | 国内访问绕境外、首屏慢;选它 |
7.5 这样有什么好处
一个短域名 + HTTPS + 全球可用 + 能随时换后端。对比只用 tcloudbaseapp.com:地址短、可做品牌、可换托管商、SEO 的 canonical 与站点名统一;代价就是 7.4 的国内延迟。
8 EdgeOne 接入:回源 + URL 重写
上一节把域名指到了 CDN,但 CDN 还不知道文件在哪、多级路由怎么找。这一节把两件事分开说:为什么需要、怎么做、做完得到什么。
8.1 为什么需要它(不做会怎样)
- 为什么一定要回源 :不用回源也能打开------最常见的省事做法是把 yangyuanchao.cn 用 301/302(重定向)跳到
xxx.tcloudbaseapp.com。但地址栏会变成那串临时域名:分享出去像测试地址、搜索引擎会把两个地址当两个站点(权重分散)、以后换托管商所有外链全断。回源的不同在于:跳转发生在服务端------访客请求 yangyuanchao.cn,EdgeOne 去源站取文件后原样返回,地址栏始终是 yangyuanchao.cn。 - 静态站的 dist 是「目录 → index.html」结构,而 CDN 默认按原样路径去源站找,
/blog/xxx会 404 → 必须配 URL 重写(重写=在 CDN 侧把请求路径改成源站真实存在的路径); - 两件事不做,域名打开就是 404 或空白。
8.2 怎么做(配置 + 顺序)
按这个顺序配,每一步都依赖上一步的结果:
- 域名系统(DNS)加 CNAME,把 yangyuanchao.cn 指到 EdgeOne 分配的加速域名;
- EdgeOne 绑定域名并签发 HTTPS 证书;
- 配回源:源站类型选「对象存储/静态托管」,回源地址填
xxx.tcloudbaseapp.com; - 配 URL 重写:把 /static/ 之外的页面路径改写到
/personal_site/dist/下(等于给目录补 index.html),/static/ 的静态资源原样回源。
先看配完的请求链路(示意):
text
访客 → DNS(yangyuanchao.cn) → EdgeOne(全球不含大陆)
├─ 命中缓存 → 直接返回
└─ 未命中 → 回源重写 ^/(.*)$ → /personal_site/dist/$1
→ CloudBase 静态托管
下面这张表是最终只保留的 2 条规则(规则越多越容易互相打架,第 9 节的坑基本都是叠加造成的):
| 规则 | 作用 | 为什么保留 |
|---|---|---|
| www → 301(永久重定向)裸域 | 把两个 origin 收成一个 | CloudBase 只认一个 origin,避免跨源资源共享限制(CORS) |
| 回源重写(/static/ 除外) | 页面路径翻译到 dist 的 index.html | 源站目录结构对不上访客路径 |
8.3 有什么好处
- 访客地址统一:裸域直接可用,www 301 收口;
- 一个入口同时承载 SPA 路由与静态资源;
- CDN 缓存 + 刷新:改完内容刷缓存,用户端立即可见;
- 出问题有明确排查面(回源错 / 重写错 / 缓存旧);第 9 节的坑表就是副产品。
9 上线首日踩的坑
规则多了会互相打架,下面按「是什么 → 为什么是坑 → 怎么解决 → 为什么能解决」排,遇到再查:
| 坑是什么 | 为什么是坑 | 如何解决 | 为什么能解决 |
|---|---|---|---|
| 重新上传 dist 后直接刷新,线上还是旧 HTML | 回源命中 CDN 缓存 | 刷缓存,确认回源指向新 dist | 缓存按 URL 存,不清就返旧副本 |
给 /static/ 配前缀 301,报 SecurityError: Failed to construct 'Worker' |
301 把脚本推到跨源,而 Worker 必须同源 | 停用该规则,worker 留在同源前缀 | 同源判定看最终脚本地址 |
同时开边缘函数改写和重定向,报 ERR_HTTP2_PROTOCOL_ERROR 200 (OK) |
两条规则同时生效,响应被改写两次 | 只保留一条 | 一个请求一条改写出口 |
给 /static/ 用前缀匹配,报 Uncaught SyntaxError: Unexpected token '<' |
HTML 被当 JS 返回 | 改「等于」精确规则 | 前缀匹配会吞掉目录索引 |
| 裸域和 www 各自回源,报 CORS 错误 | 两个 origin,CloudBase 只认一个 | www → 301 裸域收口 | 单一 origin 不触发跨源限制 |
10 你下一步能做什么
决定成败的不是工具,而是三件事:定位先于设计、规则先于实现、验证先于发布。这套流程适用于任何静态站(个人主页、文档站、产品页),只有 271 篇迁移和具体域名是这台特有的。
- 先写一页定位:访客是谁、看完要做什么、8 个页面各回答哪个问题;
- 把视觉规则和 14 项检查写成清单(色板变量、反模式、标题唯一、绝对 canonical、sitemap 对账),改完跑一遍;
- 按第 9 节的坑表过一遍域名与 CDN 配置,再开第一行页面代码。
这些内容来自哪里
这些内容来自一个真实站点从零到上线的完整记录:从定位与视觉规则,到技术选型、内容迁移、域名和访问加速接入,前后经历了几十项自动检查的反复打磨。文中的页面数、文章数与检查项数都是当时实测的结果。
相关文章
- 论坛从上线到运营工具:分区、告警与移动端第一版------同一套 CloudBase 静态托管 + EdgeOne 回源重写:这篇讲域名与不备案的取舍,那篇讲同一套配置下论坛的运营工具。
- 自研游戏埋点统计:从采集口径到后台展示------同属「网站 + 后台」这条线:这篇把站做上线,那篇把数据做成独立只读查看站。
- 搜索引擎搜不到你的文章:正文预渲染与可索引性检查:这篇讲建站与预渲染,那篇专讲「上线之后为什么搜不到」以及可索引性检查
- 部署显示成功,线上却没变:三层校验把假成功挡在上线前:同一条发布链路的下一环:这篇把站发上去,那篇确认发出去的文件真的替换了
- 网站上线后怎么确认没坏:自动巡检、失败告警与索引推送:站建好之后的日常:那篇讲每天从公网确认站点没坏,这篇讲第一天怎么建起来
- 代码块一片黑白:按需加载语法高亮,别让全站多背 1MB:同一站点前端的两处取舍:构建与预渲染在这边,体积控制在那边
- 手机窄屏上导航被挤成三行:按断点分行的取舍法:站点上线后的样式细节,同一个页头在窄屏上的取舍
- Vibe Coding 多人游戏(二十七)------ 前端性能优化(含 AI 素材管线):同为前端体积与加载取舍,一个在游戏前端、一个在内容站