[备忘录]创建本博客时的架构决策和注意事项

📅 发布日: 2023/01/01, 更新日: 2023/04/08 ⏱️ 预计阅读时间约8分钟 (3,262字)

一份全面的备忘录，涵盖静态与动态站点选择、托管平台评估、自定义Pandoc SSG架构、基于Confluence的UI设计和多语言SEO。

目录

（考虑因素 1）静态站点与动态站点？
1. 静态站点和动态站点之间的差异
（考虑因素2）选择静态站点托管平台
（考虑因素 3）选择静态站点生成器
（考虑因素 4）定制 UI 和信息设计
（考虑因素 5）SEO 策略和最佳实践
总结

（考虑因素 1）静态站点与动态站点？

评估静态网站生成器还是动态 CMS 是否更符合您的技术要求是构建网站时的关键架构决策。
这两种范式之间的选择从根本上影响功能集、开发人员体验、可维护性、可扩展性和安全状况。

静态站点和动态站点之间的差异

静态站点
纯粹由预渲染的静态资源（HTML、CSS、JavaScript、媒体文件）组成。进行内容更改需要直接重建或编辑文件。
非常适合内容保持相对一致且不需要实时用户特定数据库写入的技术文档、个人博客和信息网站。
动态站点
根据每个 HTTP 请求，通过服务器端运行时、数据库和应用程序框架动态呈现内容。
非常适合交互式应用程序、多租户协作平台、电子商务或涉及频繁实时用户交互的场景。
以下是静态和动态架构之间的优缺点比较。高优先级标准以斜体显示。

静态站点的优点

快速的页面加载速度和卓越的用户体验（TTFB / Core Web Vitals）。
源服务器上没有计算负载，可以通过 CDN 缓存轻松扩展到高流量峰值。
稳定的内容交付，停机时间或服务器崩溃风险几乎为零。
可靠的安全态势，攻击面最小（无直接数据库注入或后端漏洞）。
与动态服务器实例相比，运行和托管成本极低。

静态站点的缺点

内容更新需要运行构建/部署管道。
如果没有客户端 API，则无法执行任意后端逻辑，从而限制了交互式服务器端工作流程。
不适合需要事务数据库写入或个性化服务器会话的复杂应用程序。

动态站点的优点

丰富的实时交互性促进活跃的用户交流和社区功能。
直接从关系数据库或文档数据库支持的浏览器 GUI 轻松进行内容编辑。
通过动态插件和按需服务器端脚本实现高可扩展性。

动态站点的缺点

如果没有积极的缓存，页面响应时间会变慢，并且可能会降低用户体验。
服务器和数据库负载过重，导致基础设施和运营成本较高。
持续安全维护（修补 CMS 漏洞、SQL 注入、CVE）。

虽然动态站点使标记和搜索等横切功能更容易实现，但选择静态站点架构是为了消除维护开销并使运营成本接近于零。
参考：
静态网站和动态网站的区别、优缺点 |Xserver业务

（考虑因素2）选择静态站点托管平台

部署静态站点需要可靠的存储和 CDN 分发基础设施。
虽然由于熟悉 GCP，Google Cloud 的 Firebase Hosting 成为主要候选平台，但我们对替代平台进行了系统评估。
根据比较静态站点托管平台|JavaScript 公告，领先的托管提供商包括：

网络化
韦尔塞尔
Firebase 托管
Cloudflare 页面
GitHub 页面
亚搏体育appGitLab页面

根据四个关键标准进行评估：“日本的 Edge CDN PoP”、“通过 GitHub / Cloud Build 自动部署”、“足够的免费套餐配额”和“允许的商业用途”。

托管服务	日本CDN PoP	GitHub / 云构建部署	慷慨的免费套餐	商业用途
网络化	×	⚪︎	⚪︎	⚪︎
韦尔塞尔	⚪︎	⚪︎	⚪︎	×
Firebase 托管	⚪︎	⚪︎	⚪︎	⚪︎
Cloudflare 页面	⚪︎	⚪︎	⚪︎	⚪︎
GitHub 页面	⚪︎	×	⚪︎	×
亚搏体育appGitLab页面	⚪︎	×	⚪︎	？

Firebase Hosting 和 Cloudflare Pages 成为最有力的竞争者。
虽然 Cloudflare Pages 提供了引人注目的边缘工作人员功能，如 [Cloudflare Pages vs Firebase Hosting | 中详细介绍的]Bejamas](https://bejamas.io/compare/cloudflare-pages-vs-firebase/)， 选择 Firebase Hosting 是因为它利用我们现有的 Google Cloud 帐户基础架构，与 Google Analytics 无缝集成，并与 Cloud Build 管道本地连接。

（考虑因素 3）选择静态站点生成器

静态站点生成器 (SSG) 将源标记（Markdown、AsciiDoc）和模板编译为生产就绪的静态资产。
评估了三个具有代表性的静态站点生成器：
最初的目的是采用 Hugo 来最小化设置开销。
然而，事实证明，找到与 Atlassian Confluence 文档美学紧密匹配的现有主题很困难。因此，开发了一个利用 Pandoc 的自定义 Python 驱动构建管道。

Jekyll 优点

本机 GitHub Pages 集成。
通过 Liquid 和 Markdown 进行直观的模板.
丰富的插件生态系统。

杰基尔的缺点

Ruby 环境管理和大型站点上较慢的构建时间。

雨果·普洛斯

用 Go 编写的编译速度极快。
主题和内容清晰分离。
简单的 Markdown 创作工作流程。

雨果·康斯

Go 模板语法学习曲线和相对较少的专业社区主题。

盖茨比优点

强大的 GraphQL 数据层和丰富的 React 组件生态系统。
集成无头 CMS 后端的庞大插件库。

盖茨比的缺点

架构复杂度高、依赖性膨胀、学习曲线陡峭。

（考虑因素 4）定制 UI 和信息设计

Pandoc 跨格式转换文档（Markdown、HTML、PDF、Word）。通过使用“–template”标志指定自定义 HTML 模板，可以使用自定义布局和 CSS 样式来格式化静态页面。
Pandoc 用户指南 - 模板

Confluence 风格的侧边栏

使用 Python 和 JavaScript 开发，复制 Atlassian Confluence 空间侧边栏的简洁导航，使用户能够轻松地在类别和帖子之间跳转。
参考： Atlassian Confluence Space 侧边栏文档

目录 (ToC)

实现了一个 Python 脚本来解析 HTML 标题标签（ h2 、 h3 ）并动态生成交互式目录。
参考： DevelopersIO - 通过 Python 从 HTML 标题生成目录

代码块的语法突出显示

将 Prism.js 与“明晚”主题和自定义 CSS 颜色调整集成。
参考： Prism.js 官方网站
语言包包括 Bash、Python、Docker、YAML、JSON、Git 和 Markdown。

站内搜索

集成的 Google 自定义搜索引擎 (CSE)，在所有索引博客页面上提供强大的搜索功能，无需内存搜索服务器。

网站图标

使用 GIMP 生成并通过在线图标工具调整大小（512x512 缩小至 256x256、32x32、16x16），以确保在桌面和移动设备上呈现清晰的渲染效果。

（考虑因素 5）SEO 策略和最佳实践

搜索引擎优化 (SEO) 确保技术文章在搜索引擎结果页面 (SERP) 中排名靠前，并吸引寻求解决方案的开发人员。

1. 多语言和全球搜索引擎优化

最初专注于日本读者，该网站转变为双语（英语/日语）架构，以覆盖更广泛的全球工程受众。
在 <html> 根上配置正确的 lang 属性，并实现相互的 <link rel="alternate" hreflang="..."> 标记，以帮助 Google 提供正确的本地化页面。
部署不同的 XML 站点地图（“sitemap.xml”和“sitemap_en.xml”）以实现全面的搜索爬虫发现。

2. 图像优化

目标最佳内容宽度为 786px，具有响应式尺寸。
使用 JPG 表示复杂的摄影媒体，使用压缩的 PNG/SVG 表示技术架构图。
持续监控 Google PageSpeed Insights，以最大程度地减少 Core Web Vitals 布局变化 (CLS) 并确保快速的最大内容绘制 (LCP)。

3. 语义 HTML 和标签优化

保留正确的标题层次结构并利用自定义开放图谱协议 (OGP) 元标记（标题、描述、图像、URL）来优化 X (Twitter) 和 Slack 上的社交卡预览。
将导航结构简化为单个语义“
”容器，以实现干净的屏幕阅读器可访问性和可爬行性。

4. 社交分享和放大

为每个帖子配备快速社交分享按钮（X、Hatena 书签和本机 URL 副本），以鼓励开发人员联合和讨论。

5. 固定链接优化

标准化、干净的字母数字永久段，可防止 URL 百分比编码问题并保护爬网索引完整性。

总结

通过将静态站点简单性 (Pandoc + Python) 与 Firebase 托管和自动化 Cloud Build CI/CD 相结合，该博客在日语和英语受众中实现了接近零的运行成本、亚秒级的加载时间和坚如磐石的可靠性。

链接已复制到剪贴板！