构建实践 · 把页面、内容和交付做成工程
从设计系统、内容管线到页面实现、Docker、CI 和无障碍:这些不是“从零跑起来”必需的,但决定了项目能不能长期维护、能不能稳定交付。
对照哪个仓库
本系列讲的实现已经开源在 nuxt-blog-demo:
- 设计系统、前端页面、内容管线 —— 开源仓库里有对应实现和
docs/design-system.md、docs/design-tokens.md; - 部署与 CI —— 开源仓库提供
Dockerfile、infra/和一份 CI 工作流示例;本系列里的 ACR、VPC、发布脚本涉及真实环境,只在私有仓库; - 无障碍 —— 开源仓库保留了
frontend/e2e/里的 axe 检查。
AI 助手的部署与调优不在开源范围内,相关内容见 AI助手后端实现。
这个系列写什么
这个系列承接 从0建小站 留下的工程细节。从0建小站 已经给出完整博客实现路径,这里继续往“一个页面怎样变成可长期交付的系统”里走:
- 设计怎样从参考站收敛成 tokens;
- Markdown 怎样经过校验、聚合和 API 变成页面;
- Nuxt 页面怎样处理响应式、主题与可访问性;
- 镜像、发布、回滚和 CI 怎样形成可重复的交付链;
- 无障碍怎样从结构开始,而不是最后补 aria。
它不按时间线记录“今天做了什么”,而是按工程问题组织。每篇都尽量给出可运行的命令、代码或真实输出。
文章
设计与内容
| 编号 | 标题 | 核心问题 | 状态 |
|---|---|---|---|
| 01 | 设计与设计系统:从参考站到 tokens | 参考站翻译、AI 方向收敛、Figma、token 分层 | 初稿 |
| 02 | 内容模型(一):为什么用 Markdown 而不是 CMS | 内容所有权、frontmatter 契约、Zod 校验、日期坑 | 初稿 |
| 03 | 内容模型(二):从 Markdown 到 API | 加载与草稿过滤、标签/系列聚合、图片路径、测试 | 初稿 |
| 04 | 前端:Nuxt + SCSS 的页面实现 | 页面结构、响应式、亮暗主题、CSS Modules 坑 | 初稿 |
交付与质量
| 编号 | 标题 | 核心问题 | 状态 |
|---|---|---|---|
| 05 | 部署(一):镜像与多阶段构建 | Dockerfile 三阶段、依赖缓存、内容进镜像、本机验证 | 可读 |
| 06 | 部署(二):ACR、VPC 与回滚 | buildx 推送、VPC 私有拉取、预检、commit tag 回滚 | 可读 |
| 07 | CI(一):从 lint 到 Playwright 的质量门 | 触发条件、检查顺序、内容校验、浏览器测试 | 可读 |
| 08 | CI(二):CI 构建还是本地发布 | 三条发布路径、权限边界、commit tag 与 digest | 可读 |
| 09 | CI(三):个人发布与企业流水线 | 权限、审批、审计、复现四个维度、升级条件 | 可读 |
| 10 | 无障碍(一):跳转链接、焦点与语义结构 | 跳过导航、焦点环、landmark、aria 状态、对比度 | 可读 |
| 11 | 无障碍(二):主题切换与 axe 修复 | 可访问名称、SSR 水合、axe 边界 | 可读 |
推荐读法
| 目标 | 顺序 | 说明 |
|---|---|---|
| 改设计系统 | 01 → 04 → 10 | tokens、页面结构、无障碍基线 |
| 改内容管线 | 02 → 03 | frontmatter、加载、聚合、图片与测试 |
| 准备上线 | 05 → 06 → 08 | 镜像、发布、回滚、发布路径 |
| 补质量门 | 07 → 08 → 09 | CI 检查、CI 与发布边界、流程升级 |
| 做可访问性 | 10 → 11 → 04 | 语义、焦点、主题切换与 axe |
与其它系列的关系
- 从0建小站:背景、架构、内容管线、接口、页面、主题和构建;先读它再读这里。
- 如何优化:性能测量、字体图片和 AI 回答调优;构建完成后再看。
- 搭建AI助手前端:聊天界面与同源代理,和本系列的 Nuxt 代理、可访问性有交叉。
- AI助手后端实现:FastAPI、pgvector 和 RAG,不依赖前端构建细节。
状态与维护
- 01–04 是初稿,
draft: true;05–11 可读。 - 系列就是所在文件夹,文件夹名
04-构建实践就是系列名;00-目录.md是系列第一篇,和其余文章一样有 slug、详情页和正文。 - 系列入口和首页系列卡片都跳到这篇目录文章;正文里的相对
.md链接会自动改写成站内地址。 - 文章 slug 规则是
<英文系列>-<两位序号>-<英文主题词>,本系列以build-practice-开头,例如build-practice-01-design-system、build-practice-05-deployment-docker。 - 新增或移动文章时,同步更新本页的链接、状态和阅读路线。