先看线上效果
网站已完成 ICP 备案和公安备案并部署上线，可以直接访问体验：
- 在线访问：https://yaohewoma.cn
- GitHub 主页：yaohewoma · GitHub
整个项目从 0 用 TRAE Design Canvas 可视化搭建，8 个页面在画布上全互联，点击导航即时跳转。下面分享完整的开发过程和踩坑经验，包括那些让我反复返工的瞬间。
一、项目概览
最终成果
| 页面 | 文件 | 说明 |
|---|---|---|
| 首页 | index.html | Hero + 项目卡片 + 博客预览 + 社区数据 |
| 项目展示 | projects.html | 3 个项目详情 + 技术雷达 + 时间线 |
| 技术博客 | blog.html | 2 篇文章列表 + 分类 + 侧边栏 |
| 开源贡献 | opensource.html | GitHub 热力图 + 项目卡片 + 个人主页 |
| 关于我 | about.html | 个人故事 + 技能进度条 + 装备 + FAQ |
| 文章详情 ×2 | article.html / article-zhang.html | 每篇独立详情页，含目录/代码块/引用 |
| 404 页面 | 404.html | 错误页 + 导航回首页 |
技术栈
整个站点刻意保持轻量，没有构建步骤，没有 npm install，改完 HTML 刷新就能看效果。
- 纯 HTML/CSS/JS 为主
- Tailwind CSS（Browser CDN v4.3.1）+ 自定义 CSS 变量做主题系统
- Lucide Icons（CDN v1.8.0）
- 原生 JS 动画 + Intersection Observer 滚动揭示
.design文件管理页面节点和交互映射
关于"倾向闭源但部分开源"这件事，我在网站里也如实写了——不是所有项目都开源，但有价值的项目会开放出来。这种诚实的表述比一味标榜"全部开源"更符合实际情况。
二、Design Canvas 的核心机制
1. .design 文件结构
每个 .design 项目本质是一个 JSON 文件，描述页面的拓扑关系：
{
"data": [
{
"id": "page-index",
"title": "首页",
"type": "page",
"canvasData": { "x": 0, "y": 0, "group": 0 },
"devMetadata": {
"htmlSrc": "index.html",
"interactions": [
{
"domId": "nav-projects",
"targetPageId": "page-projects"
}
]
}
}
],
"config": {
"showEdge": true
}
}
几个关键字段：
htmlSrc指向 HTML 文件路径interactions数组定义页面跳转关系domId对应 HTML 中的data-dom-id属性targetPageId指向目标页面的idhideEdge: true可以隐藏连接线（用于同页面的自连接）
2. data-dom-id 是连接线的关键
Canvas 通过 data-dom-id 属性识别可点击的导航元素。HTML 中只要有这个属性的 <a> 标签，就会在画布上生成连接线。
<!-- 这个链接会生成连接线 -->
<a href="projects.html" data-dom-id="nav-projects">项目展示</a>
<!-- 这个链接不会生成连接线 -->
<a href="projects.html">项目展示</a>
这个机制听起来简单，但实际开发中我在这上面踩了最大的坑——后面会详细说。
三、开发过程中的关键问题和解决方案
问题 1：Canvas 渲染报错 — 安全策略
现象：点击导航菜单时，Canvas 控制台报错：
Failed to read a named property 'removeEventListener' from 'Window':
An attempt was made to break through the security policy of the user agent.
原因：页面过渡动画中使用了 window.location.href 跳转，Canvas 的 iframe 沙箱不允许这种方式，触发了安全策略。
解决：在点击处理器的最前面加 iframe 检测，在 Canvas 环境中跳过自定义过渡，直接让浏览器处理链接：
document.addEventListener('click', function(e){
try{
var link = e.target.closest('a[href]');
if(!link) return;
var href = link.getAttribute('href');
if(!href || href.startsWith('http') || href.startsWith('mailto')
|| href.startsWith('#') || href.startsWith('javascript:')) return;
if(href.indexOf('.html') === -1) return;
// 关键：在 iframe（Canvas）中跳过自定义过渡
if(window.parent !== window) return;
e.preventDefault();
// ... 自定义过渡动画
setTimeout(function(){ window.location.href = href; }, 500);
}catch(e){}
});
这一行 if(window.parent !== window) return; 是整个兼容方案的灵魂。
问题 2：导航栏位置不一致
现象：不同页面的导航栏位置和样式有细微差异，切换页面时能感知到跳动。
原因：每个页面的 <header> 使用了不同的 backdrop-filter、透明度和 border 颜色。单独看每个页面都没问题，但连起来看就暴露了。
解决：全站统一 header 样式：
<header id="site-header" class="sticky top-0 z-50 border-b"
style="border-color: var(--color-border);
background-color: rgba(250,246,241,0.92);
backdrop-filter: blur(12px);
-webkit-backdrop-filter: blur(12px);">
同时确保所有页面的桌面导航使用 class="flex" 而不是 class="hidden sm:flex"，否则 Canvas 在窄宽度渲染时找不到导航链接，画布上会一片孤岛。
问题 3：页面间没有连接线
这是花时间最多的问题，原因是三层问题叠加，必须逐层排查。
现象：部分页面在画布上没有连接线，点击导航无法跳转。
原因拆解：
- 部分页面缺少
data-dom-id属性 .design文件中缺少对应的interactions映射- 导航链接路径错误（
../index.htmlvsindex.html）
解决：逐项修复。
路径修复：所有 HTML 在同一目录，用相对路径：
❌ href="pages/projects.html" （多了 pages/ 前缀）
❌ href="../index.html" （多了 ../ 前缀）
✅ href="projects.html" （同目录直接引用）
data-dom-id 补全：每个页面的 5 个导航链接都需要：
<a href="index.html" data-dom-id="nav-index">首页</a>
<a href="projects.html" data-dom-id="nav-projects">项目展示</a>
<a href="blog.html" data-dom-id="nav-blog">技术博客</a>
<a href="opensource.html" data-dom-id="nav-opensource">开源贡献</a>
<a href="about.html" data-dom-id="nav-about">关于我</a>
.design 交互映射：每个页面节点都需要 5 个交互：
{
"domId": "nav-index",
"targetPageId": "page-index",
"hideEdge": true
}
hideEdge: true 用于自连接（比如首页的"首页"链接），避免画布上出现自环线把拓扑图搞乱。
排查这类问题的经验是：HTML 和 .design 文件要双向对照，缺一不可。只改 HTML 不改 .design，或者反过来，连接线都不会出现。
问题 4：文章正文与论坛原文不符
这个坑让我意识到——设计稿里预置的内容不能直接用。
现象：设计稿作者为文章预置的正文是编造的，和我在论坛发的原文对不上。最离谱的是把 KineTap 错误描述成"手势识别工具"，而实际上它是"桌面快捷方式一键播放的辅助沟通工具"——这两个东西的技术路线完全不同。
原因：设计稿的占位内容往往是作者凭想象写的，上线前必须对照真实信息逐字核对。
解决：基于论坛原文重写每篇文章正文。以 KineTap 文章为例，把虚构的描述全部替换成真实信息——
- 修正核心错误：手势识别 → 桌面快捷方式一键播放
- 补充真实数据：5MB 包体、171 个话术、完全离线
- 添加真实代码块：Kotlin
ShortcutManager.kt（ShortcutInfoCompat.Builder） - 加入真实获奖信息：Trae 挑战赛 · 科技至善赛道 · 人气公益作品奖
文章链接也加上 data-dom-id，在 .design 文件中建立映射：
{
"domId": "article-zhang",
"targetPageId": "page-article-zhang"
}
这样画布上 blog 页面会有连接线指向每篇文章，形成清晰的页面拓扑。
问题 5：默认主题跟随系统导致跳页变暗
现象：每次切换页面，主题都会自动切换到系统主题（夜间模式），用户反馈"夜间主题太丑了，每次切换页面都会自动切换到系统主题这样很不好"。
原因：主题初始化代码用了 prefers-color-scheme 媒体查询：
// ❌ 跟随系统
var theme = saved || (prefersDark ? 'dark' : 'light');
解决：改成默认浅色，不跟随系统，只认本地存储的偏好：
// ✅ 默认浅色，不跟随系统
var theme = saved || 'light';
同时 HTML 标签也统一改成 <html lang="zh-CN" data-theme="light">，避免 FOUC（无样式内容闪烁）。
四、设计系统实践
CSS 变量统一管理
全站使用 CSS 变量定义颜色系统，方便后续换主题：
:root {
--color-brand: #B85E35; /* 主品牌色 — 赤陶橙 */
--color-brand-dark: #8E4422;
--color-brand-bg: #FCEEE4;
--color-accent: #457A6C; /* 强调色 — 鼠尾草绿 */
--color-accent-dark: #355F53;
--color-bg: #F8F5F0; /* 背景色 — 暖米白 */
--color-bg-alt: #F0EBE3;
--color-text: #181412;
--color-text-muted: #87807A;
--color-border: #E5DDD0;
--font-display: 'Playfair Display', 'Noto Serif SC', serif;
--font-body: 'Inter', 'Noto Sans SC', sans-serif;
--font-mono: 'JetBrains Mono', monospace;
--container-max: 1120px;
}
选色思路：赤陶橙 + 鼠尾草绿这组配色，是想做出"温暖人文"的感觉，不是常见的科技蓝紫。背景用暖米白 #F8F5F0 而不是纯白，视觉上更柔和，长时间阅读不刺眼。
明暗双主题靠 data-theme 属性切换：
[data-theme="dark"] {
--color-bg: #12100E;
--color-brand: #CF7D52;
--color-text: #EDE8E2;
/* ... */
}
暗色主题没有简单地把颜色取反，而是单独调了一组"暖夜"配色——背景偏暖棕而非冷黑，品牌色提亮一档保证对比度。
动画体系
三层动画提升体验，但都克制使用，不喧宾夺主：
- 入场动画：Intersection Observer + CSS transition，元素进入视口时淡入上滑
- 交互动画：卡片 hover 上浮 + 发光，按钮 hover 缩放
- 细节动画：滚动进度条、返回顶部按钮、磁吸按钮效果
后来移除了全屏加载转圈和页面切换时的"长方形从上往下飞"过渡动画——用户反馈这两个动画反而影响体验，页面直接出现比等动画结束更舒服。这是个教训：动画不是越多越好，干扰内容的动画就是噪音。
响应式
断点覆盖所有设备：
- 桌面端：完整布局
- 手机端（
max-width: 640px）：单列堆叠、减小字号、禁用 hover 变换、优化触摸目标（min-height: 44px）
移动端还特意禁用了卡片的 transform hover 效果，因为触屏没有 hover，留着只会造成触摸瞬间的闪烁。
五、踩坑总结
| 坑 | 原因 | 解决方案 |
|---|---|---|
| Canvas 报安全策略错误 | iframe 沙箱限制 | if(window.parent !== window) return; |
| 导航栏位置不一致 | header 样式不统一 | 全站使用相同的 header 标签和样式 |
| 页面没有连接线 | 缺少 data-dom-id |
HTML 和 .design 文件双向补全 |
| 链接跳转 404 | 路径多了 ../ 或 pages/ |
同目录用相对文件名 |
| 导航在 Canvas 中不可见 | hidden sm:flex 在窄宽度隐藏 |
改为 flex 始终可见 |
| 文章正文与论坛原文不符 | 设计稿预置内容是编造的 | 基于论坛原文逐篇重写 |
| 默认主题跟随系统 | 代码用了 prefers-color-scheme |
改为 var theme = saved || 'light' |
| 全屏加载动画影响体验 | 转圈和飞入动画干扰内容 | 移除过渡动画，页面直接出现 |
| HTTPS 证书 | 需要加密链接 | certbot + Let’s Encrypt 自动续期 |
六、部署上线
网站最终部署在阿里云 ECS（Ubuntu 24.04 + Nginx 1.24），用 Let’s Encrypt 申请了免费 SSL 证书，certbot 自动配置 Nginx 并设置定时续期，HTTP 自动 301 跳转到 HTTPS。
# 一行命令搞定 HTTPS
sudo certbot --nginx -d yaohewoma.cn -d www.yaohewoma.cn \
--non-interactive --agree-tos --email your@email.com --redirect
备案号 豫ICP备2026027991号-1 加到了 8 个页面的底部，点击跳转工信部查询网站。公安备案号拿到后也会同样加到底部。
七、最终效果
画布拓扑
8 个页面节点，通过 data-dom-id 和 .design 交互映射形成完整连接网络：
- 首页 ←→ 项目/博客/开源/关于（双向连接）
- 博客 → 2 篇文章详情（单向连接）
- 每篇文章 ←→ 博客（返回连接）
- 404 页面 ←→ 所有主页面（导航连接）
从设计到代码
Canvas 上画好的页面节点，配合 data-dom-id 标注，能直接生成可跳转的 HTML 骨架，省掉了手动维护导航链接的功夫。整个开发流程是：画布规划拓扑 → 生成 HTML 骨架 → 填充内容 → 核对真实信息 → 部署上线。
八、给 Design Canvas 用户的建议
-
先规划页面拓扑再写代码：在
.design文件中先定义好页面 ID 和交互关系，再开始写 HTML，避免后期补data-dom-id的痛苦 -
data-dom-id是核心：每个需要跳转的链接都要有这个属性，否则 Canvas 无法识别连接关系 -
注意 iframe 沙箱限制：Canvas 在 iframe 中渲染页面，
window.location跳转会触发安全策略，务必加 iframe 检测 -
统一 header 结构：所有页面的导航栏使用完全相同的 HTML 结构和 CSS 样式，避免页面切换时的视觉跳动
-
路径用相对文件名：所有 HTML 放在同一目录，链接直接写
projects.html，不要加pages/前缀或../父路径 -
善用
hideEdge：自连接（如首页的"首页"链接）设置hideEdge: true，避免画布上出现杂乱的自环线 -
设计稿内容要核对：预置文案往往是占位或编造的，上线前一定要对照真实信息逐字核对，否则容易闹笑话——这是我最深的教训
-
动画克制使用：不是越多越好，干扰内容的动画就是噪音。用户要的是快速看到内容，不是等你的转圈动画放完
-
默认主题别跟随系统：除非你明确想要跟随系统，否则默认浅色 + 本地存储偏好是更稳的方案
九、写在最后
这个项目让我对"可视化搭建"有了新的理解。Canvas 解决的是页面拓扑的可视化管理问题——哪个页面连到哪个页面，画布上一目了然，不用在代码里来回找链接。但它不解决内容问题，设计稿里的占位内容、编造文案，最终还是得人工核对。
技术工具能帮你快速搭起骨架，但血肉还得自己填。KineTap 那篇文章如果不是回头核对论坛原文，差点就把"手势识别"这个错误描述发出去了。这件事提醒我：工具越快，人越要慢下来核对事实。
如果这篇分享对你有帮助，欢迎到 https://yaohewoma.cn 看看实际效果，或者在 https://github.com/yaohewoma 给个 Star。
有问题也可以在评论区交流，我会持续更新这个项目的开发过程。