11-单文件H5宣传站-一个人怎么写出项目官网系列AI 伙伴AI-Partner——具身智能陪伴机器人 · 数据接口部署与二次开发篇11/12一、先抛问题项目官网到底需要多重AI 伙伴AI-Partner是个四端项目后端/视觉/硬件/文档但对外介绍它只需要一个东西——一个能打开、好看、讲清楚这是台会陪伴的机器人的网页。项目的选择相当决绝一个web/index.html六百多行完事。没有构建工具没有 node_modules没有框架。这个选择值不值得抄值。往下看为什么。二、为什么选单文件自包含方案先摆事实项目源码盘点维度实现方式单文件全部 HTML/CSS/JS 内联于一个 index.html共 648 行内联 CSSstyle内约 273 行:root定义设计变量内联 JS3 个 IIFE移动端菜单、Toast 提示、滚动显现动画外部依赖仅 1 个字体Google Fonts 的飞书镜像图标/favicon 全是内联 SVG 或 data URI图片3 张本地图片hero.jpg首图、elder.jpg长辈场景、child.jpg儿童场景框架零。无 JS 框架、无 CDN 库单文件方案的优势全是一个人的项目最需要的零构建不装 Node、不配打包器改完保存刷新即所见。对宣传站这种偶尔改一句文案的页面Vite/Next 的热更新优势完全体现不出来而工程化的维护成本依赖升级、构建报错、CI 配置却是实打实的。随便丢哪都能打开双击本地文件、扔进任何静态托管、塞进服务器 Nginx 目录甚至直接发给朋友——它都能跑。没有后端依赖不存在服务挂了官网打不开。方便随项目打包它就在项目仓库的 web/ 目录里跟代码一起走版本管理谁 clone了仓库谁就拥有完整官网。一句话总结宣传站的本质是一张会动的海报海报不需要微服务架构。什么时候该换正经工程文末说。再补一张成本对比账帮你下决心示意维度单文件 H5Vite/Next 工程环境准备一个文本编辑器Node 版本管理 依赖安装首次上线耗时保存即发布脚手架 构建配置 部署流水线日常改文案改一行存一行改代码 → 构建 → 部署依赖风险无几乎零依赖依赖树升级、安全通告、构建失败性能无框架运行时加载即渲染需要优化包体、代码分割能力上限静态展示与轻交互数据驱动、复杂状态、多页面结论很直白能力上限决定选型。你只需要讲清楚项目就别背工程化的行李。三、内容叙事九个区块怎么把故事讲完单文件不只是技术方案页面结构本身就是一次完整的产品路演。AI 伙伴AI-Partner宣传站的区块顺序值得逐个复盘区块讲什么叙事作用导航 Hero一句话定位 首图3 秒内让访客知道这是什么价值区陪伴而非工具的核心主张回答为什么存在六大核心功能对话/记忆/提醒/守护等能力回答能做什么系统架构端边云三层协作回答怎么做到的给技术受众应用场景长辈/孩子两张场景图回答和我有什么关系技术栈卡LangChain4j、YOLO11、MQTT、RK3566 等技术可信度背书路线图四阶段时间轴已完成/开发中/规划中/展望展示可持续性如实标注进度CTA footer行动号召收口转化两个叙事细节可以抄其一技术栈区对非技术访客是信任状对技术访客是选型说明一份内容服务两类人群其二路线图如实区分已完成/开发中/规划中不把展望画成现状——这既是诚实也是给自己留退路。四、内联 CSS/JS 的组织方式与可维护性技巧“单文件不等于一团乱麻”。这个项目的组织挺有章法CSS 侧用:root设计变量统一管理色彩体系如背景色#FBF6EE、品牌金#E8A33D这类暖色调契合陪伴场景全站改主题色只动一处。区块顺序与页面结构一致导航 → Hero → 价值主张 → 六大核心功能 → 端边云架构图 → 应用场景 → 技术栈 → 路线图 → CTA → footer找样式先定位区块而不是全局搜 class 名。JS 侧三个 IIFE立即执行函数各管一摊互不污染全局// 结构示意(functionmobileMenu(){/* 汉堡菜单开合 */})();(functiontoast(){/* showToast(msg) 纯反馈不跳转 */})();(functionreveal(){/* IntersectionObserver 滚动显现 */})();可以学到的技巧交互全部够用就好——按钮点击用data-toast属性委托触发 Toast加入内测这类动作在还没有后端入口时先给个明确反馈比死链接强导航锚点滚动用原生平滑滚动动画尊重系统设置后面讲。五、响应式双断点的实现页面只用了两个媒体查询断点960px 和 640px覆盖桌面与移动两种形态断点典型调整media (max-width: 960px)多列网格降列数隐藏桌面导航出现汉堡菜单media (max-width: 640px)进一步单列化字号与间距压缩移动端还做了viewport-fitcover适配刘海屏安全区。双断点是最务实的粒度一个平板、一个手机比七八个断点好维护得多。网格布局用 CSS Grid降列只需改一个grid-template-columns代价极低。新手做响应式先学这套两档降级思路比一上来就研究容器查询实在。另一个容易被忽略的细节动画块对prefers-reduced-motion做了适配——用户系统开启减少动态效果时关闭滚动动画。这是无障碍意识的体现一行媒体查询的事建议人人都加。六、配色与排版决策整体是暖米色底 品牌金强调色的居家暖调而非科技蓝黑——这是有意的品牌决策产品卖点是陪伴与温度视觉就该像客厅而不是机房。正文用了衬线中文字体宋体系做标题、黑体系做正文衬线带来书卷气/家人感。给你的启示配色跟着产品情绪走而不是跟着哪个颜色显得高级走。老人用户还意味着字号不能抠门、行高要宽松这些在移动断点里都做了放大处理。七、图片资源与体积权衡3 张本地图hero/elder/child.jpg 全部内联 SVG 图标。选择逻辑如下资源方案理由大场景图首图/场景图本地 jpg与页面一起打包不依赖外部服务控制好压缩体积首屏图建议压到百 KB 级小图标内联 SVG一个 icon 几百字节外链反而多一次请求favicon内联 SVG data URI又省一个文件别上 CDN 的理由单文件方案的灵魂是无外部依赖也能开图片走 CDN 等于把灵魂拆了一半而且个人项目图省事挂第三方图床哪天床塌了官网集体裂图。要压缩体积正确姿势是本地压图WebP/压缩 jpg。八、那一个外部字体依赖风险与降级全站唯一的外部命门是字体通过一个 Google Fonts 的国内镜像加载 Noto Serif SC / Noto Sans SC并做了preconnect预连接加速。风险必须讲透镜像可用性不可控镜像挂了字体加载失败或超时——好在字体加载是异步且非阻塞的页面不会白屏只是回退到系统字体。降级方案要预先写好font-family栈里必须排在系统字体前面写好回退如Noto Serif SC, Source Han Serif SC, SimSun, serif且font-display: swap类策略让文字先用回退字体渲染、字体到位后再替换避免长时间看不见字。经验法则单文件自包含允许极少数外部依赖但每一个都必须死了也不影响阅读。字体、统计脚本都属此类。九、SEO 与分享卡片的现实单页 SPA 式宣传站的内容是静态 HTML 直出这一点比纯客户端渲染的框架站强——搜索引擎能直接读到全部文字。但也要认清现实单页没有多页面路由SEO 关键词全押在一个页面上长尾内容做不了社交分享卡片微信/聊天工具预览图需要meta的 og/描述标签齐备单文件里手写维护即可没有 sitemap、没有结构化数据的余地——对一个项目宣传站这些局限完全可以接受真要运营内容营销再考虑上正经框架。十、可访问性细节清单抄作业要点照着自查检查项项目做法自查方法对比度暖底色上正文用深色勿用浅灰大段文字用对比度工具验正文 ≥ 4.5:1字号移动端放大正文字号老年用户场景手机实机看一眼点击区域按钮与菜单项留足内边距手指能否一次点中减少动效prefers-reduced-motion关闭动画系统开启减弱动态后检查键盘可达导航/按钮用原生元素而非 div 拼的假按钮Tab 键走一遍图片语义img 标签写 alt阅读器能否读出图意十一、单文件宣传站骨架清单 何时升级工程化给你一份可复制的骨架清单结构对照 AI 伙伴AI-Partner的实现headviewport、charset、SEO 描述与分享 meta、preconnect如有字体、style设计变量 → 布局 → 组件 → 断点结构nav锚点汉堡→ hero → 卖点区 → 功能区 → 架构/原理图 → 场景区 → 技术栈 → 路线图 → CTA → footer资源大图 3 张以内本地化图标全 SVG 内联脚本≤3 个 IIFE菜单/Toast/滚动显现原生 API 不引库收尾reduced-motion 适配、alt 补全、移动实机走查。什么时候该上正经前端工程三个信号命中任意一个就该搬① 要接后端真实数据表单提交、预约、状态查询需要接口层与状态管理② 页面膨胀到改一处牵全身多个页面出现重复代码③ 需要多人协作或上线灰度/实验能力。到那天把设计变量、文案、区块结构平移进 Vite Vue/React 项目即可——单文件时代的每区块一个 class 前缀习惯会让迁移无痛很多。一个人的项目官网是它的脸面。用 648 行换一张不需要维护的脸这笔账划算。