★ FEATURED ARTICLE 接手这个需求的时候领导给的需求很简单——“把官网新版做出来先拿个demo看看效果记住是81。”一开始我以为听错了官网demo还带个加号后来才明白所谓81就是8个常规页面加1个亮点功能。8个页面负责把公司的产品、方案、内容讲清楚剩下那个“1”负责让看demo的人记住你。做demo不是做正式站但又要比随便拼的静态页高级很多。这篇就把我整个落地过程拆开聊包括需求拆解、技术选型、页面实现、那个“1”的玩法以及一堆光看文档绝对学不到的坑。1. 需求拆解与整体设计1.1 “81”到底是什么先解释一下这个81的构成我们在内部反复确认后定成了这样一张清单首页品牌定位、核心产品入口、客户案例节奏产品列表页展示所有产品/服务的入口产品详情页针对单个产品的特性、参数、调用方式行业解决方案页按行业场景聚合内容关于我们页公司介绍、发展历程、团队价值观行业动态页新闻、公告、更新日志文档与知识库页快速上手、FAQ、API参考联系我们页表单、合作邮箱、地图/二维码最后那个“1”我们做的是在线智能体问答Demo——一个嵌在官网里的对话窗口访客可以直接提问后台通过智能体框架自动回复。为什么选这个做亮点因为官网最容易做成“电子宣传册”一旦加上能跑的交互功能让人动手玩一下领导和客户就都不是在看PPT而是在“用”官网了。如果你也在做类似官网demo我的建议是先别急着开写代码把页面清单列出来哪怕不用“8”这个数字也要先明确哪些页面是信息型、哪些是转化型、哪些是交互型。这决定了整套布局和路由结构。1.2 设计思路Demo也要有产品思维很多人觉得demo就是拿前端框架套个模板放几张图、几段文字就完事。但官网demo的受众很明确一个是内部决策层要评估新版是否值得推另一个是外部种子客户要感受品牌和产品力。所以我给这个demo定了三个原则一眼看懂品牌定位、三秒钟能找到核心产品、能动手就绝不静态展示。信息架构上我们用了“F型”浏览模型来排首页顶部导航只放6个一级入口首屏只放一句主Slogan、一个产品入口和一个聊天Demo入口。中间区域放两段产品截图底部放客户logo墙和联系入口。不要一上来就堆满轮播图、弹窗、悬浮按钮demo阶段先做减法。做demo的另一个常见误区是把所有视觉稿都做完再切图。我更推荐“页面产出三角色”先做内容和信息层级再定核心组件最后才补视觉细节。比如产品列表页如果产品只有5个先想清楚是用大卡片还是表格别先去抠渐变和阴影。2. 技术选型与项目骨架2.1 为什么选了Vite Vue3而不是全站静态化官网demo通常是短周期交付所以“开发体验”比“运行时性能”更重要。我最后选了Vite Vue3 Pinia VitePress这套组合文档站部分用VitePress核心原因有几点Vite秒级热更新调一个页面的样式不用等两秒Vue3的Composition API很适合把页面拆成可复用逻辑VitePress能直接写Markdown文档和动态页能共用一套导航和主题。当然如果团队更熟Next.js完全可以用它SSR对真实官网确实有SEO优势但demo阶段我更看重快速验证和mock效率。如果你之后要无缝过渡到生产环境可以再评估Nuxt或Next。这里没必要跟风选团队最熟、能最快出活的方案就好。项目结构上我没有用特别花哨的架构保持简单、按页面拆目录website-demo/ ├─ index.html ├─ vite.config.ts ├─ src/ │ ├─ components/ │ │ ├─ layout/ │ │ │ ├─ NavHeader.vue │ │ │ └─ Footer.vue │ │ ├─ home/ │ │ └─ shared/ │ ├─ views/ │ │ ├─ home.vue │ │ ├─ products.vue │ │ ├─ product-detail.vue │ │ ├─ solutions.vue │ │ ├─ about.vue │ │ ├─ news.vue │ │ ├─ docs.vue │ │ └─ contact.vue │ ├─ stores/ │ ├─ api/ │ └─ router/ └─ docs/ ├─ index.md └─ guide/这套结构够用了真正的产品官网可以再拆业务模块但demo阶段搞太多抽象层反而会让写代码的人想跑路。2.2 页面路由和Mock数据设计官网demo的路由我用了createWebHistory而不是hash模式。虽然静态托管需要额外配一下但URL好看也更接近生产状态。路由表按页面清单写每个页面对应一个视图一共8组路由。产品详情页需要动态路由比如/product/:id。同时预留了/agent-demo这个亮点页路由但这个页面我嵌套进了首页的对话组件没有做独立导航入口避免给访客造成“官网还能聊天”的错乱感。Mock数据我用的是vite-plugin-mock直接在开发环境拦截API。这样做的好处是demo阶段不用依赖真实后端所有产品、动态、FAQ都是本地JSON数据。你可以在src/api下面定义几个函数然后通过mock返回模拟数据。等到真实后端就绪替换baseURL就行。3. 八个基础页面的实现与细节3.1 首页定调全站别贪多首页是官网demo的脸面我花了近一半时间在这上面。整个首页我用组件拆成了五个区块顶部Nav、Hero区、产品亮眼区、解决方案预览区、底部CTA。首屏Hero没有用大背景图而是用了一段CSS渐变加上一张产品界面截图优化了图片体积后首屏加载能稳定在1秒内。首页也需要考虑真实数据。我建议不要用网上随手找的图片最好用产品真实截图哪怕是线框图也比空图好。另外把客户logo墙做成可横向滚动的条就算只有5个logo也可以做成轮播显得数量多一些。这个不算欺骗是视觉优化。在Hero区底部我放了一个“智能问答Demo”的悬浮入口点击后弹出对话框。这是“1”功能的入口。做这个入口的时候才发现官网首页的核心视觉元素不能太多弹窗动作一定要单一否则用户不知道该点哪里。3.2 产品列表与详情页数据驱动页面结构产品列表页内容不多时很容易做得空旷。我采用了大网格卡片布局卡片包含产品名称、一句话描述、产品类型标签和“查看详情”链接。卡片高度固定图片比例统一为16比10代码里用了object-fit: cover裁剪。列表数据来自本地mock定义为一个含6个产品的数组包括API网关、数据报表、消息推送等不同类目。点击一张卡片就进入动态详情页。产品详情页是8个页面里最容易“翻车”的因为内容多、层级复杂。我拆成了左右分栏左侧是产品概述、功能列表、价格说明右侧是用户评价和常见问题。如果产品细分为子功能模块可以用锚点跳转加滚动监听。详情页底部一定要放一条“立即咨询”或“试用Demo”的CTA这是官网核心转化动作。关于动态路由的注意点在Vue3里从列表页跳到详情页如果组件复用onMounted不会重新触发。需要在watch路由的params或使用onBeforeRouteUpdate重新拉取数据。我因为这个吃过亏列表页点了一个产品再返回再点另一个详情数据总是不变。3.3 内容型页面用内容组织代替堆砌关于我们、行业动态、知识库这几个页面本质都是内容型很容易被做成“大段文字两张照片”。为了不显得敷衍我做了一个“侧边目录正文内容”的布局。行业动态页用一个竖向timeline来展示新闻时间轴核心不是写死样式而是一个数组按日期字段排序后渲染成垂直列表。关于我们页相对简单但不要只放一个公司介绍。我加了三个关键模块发展历程横向时间轴、团队核心成员卡片头像、公司资质荣誉墙。团队头像没有真实照片时用了初始头像彩色底效果不错。整个页面用极少的动效只在滚动到时间轴时加了一个淡入上移动效保持品牌稳重感。文档与知识库页是容易被忽略但其实很重要的页面。我直接用VitePress搭了一个子站点挂在主站/docs/路径下。这样做的好处是Markdown写文档、自动生成侧边栏、支持搜索、代码高亮。不用自己再造一套富文本编辑器省了很多功夫。如果你的官网主要是文档驱动这个方案强烈推荐。3.4 解决方案与联系页让表单成为转换点解决方案页采用“行业分类Tab切换”的方式展示。Tab切换的时候不用跳路由用一个计算属性过滤当前应显示的内容。切换按钮放在左侧内容区域放行业案例和对应产品组合。这套交互很常见但demo里最重要的一点是每个Tab切换时页面URL不变如果你想支持分享到指定Tab可以用query参数加上初始项。联系我们页是8个页面里交互场景最明确的无非表单联系方式。表单我做得很克制姓名、手机、需求描述三个字段不要公司规模、不要下拉套餐类型。提交按钮点击后不真正发请求而是弹出模拟成功提示代码里用setTimeout模拟2秒后成功并清空表单。为了演示意义我在控制台打了一条log[demo] form submitted, will integrate real API later这样看demo的同事也不会误解为已经上线了。页脚放了三列产品导航、文档导航、联系方式。社交链接虽然是#占位但我用了真实图标字体保证视觉不跑偏。这里要强调所有内页页脚要与首页页脚保持一致很多人会忽略这个细节结果每页页脚样式都不一样demo就显得很廉价。4. 第“1”个亮点一个能跑的智能体Demo4.1 为什么用智能体概念而不是普通聊天机器人官网最常见的交互亮点是“在线客服”但那种自动回复机器人的体验已经很陈旧很多公司都见识过。这次我决定做成“智能体问答”——访客不仅问“你们产品多少钱”这种销售问题还能问技术问题、让AI帮你查产品文档、甚至做小型的选型建议。这就从客服升级成了“懂产品的助手”。我选择了agno智能体框架来做后端。agno是一个面向大模型应用层的轻量框架支持快速定义agent记忆、工具调用和知识库。为什么选它而不是更重的LangChain因为demo只需要一个智能体API文档简单模型调用也能直接用标准接口。agno的抽象更少调试起来更快。后端我用FastAPI写了一个简单接口访客发送消息后端组装上下文调用LLM返回答案。当然这个功能要跑起来需要一个LLM的API key价格也不高。如果是内部demo我更推荐用本地小模型或兼容接口提前准备好key否则演示现场翻车就是事故了。4.2 后端智能体接口与前端接入后端核心代码大概是这样from fastapi import FastAPI from fastapi.middleware.cors import CORSMiddleware from pydantic import BaseModel from agno.agent import Agent app FastAPI() app.add_middleware( CORSMiddleware, allow_origins[http://localhost:5173], allow_methods[POST], allow_headers[*], ) agent Agent( modelgpt-4o-mini, instructions[ 你是官网助手熟悉产品文档和FAQ。, 回答要简洁先给结论再给补充信息。, 如果不知道就明确说需要转接人工。 ], ) class ChatItem(BaseModel): message: str app.post(/api/chat) async def chat(item: ChatItem): response agent.run(item.message) return {reply: response.content}前端我在src/api/chat.js里封装了fetch POST请求在对话组件里维护一个消息数组async function sendMessage(text) { messages.push({ role: user, content: text }); const res await fetch(/api/chat, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ message: text }) }); const data await res.json(); messages.push({ role: assistant, content: data.reply }); }由于开发环境前后端端口不同我在vite.config.ts里配置了proxy代理把/api代理到http://localhost:8000这样前端代码里不会写死后端地址生产环境部署时只要改proxy或CORS即可。注意如果你直接把前端静态页发给别人打开没有通过vite启动代理配置就不生效请求会直接404。所以演示时需要确保vite服务还在跑。4.3 演示环境与性能上的几个小心机智能体Demo要演示得顺畅有几个点一定要处理好。第一模型回复有延迟前端至少要做两件事显示“正在输入”的动画消息发出后立刻把用户消息滚动到可读取的区域。第二对话历史要保存在组件内部不要刷新页面后消失可以放到localStorage但注意别放敏感信息。第三设置一个“清空对话”按钮因为评委/客户可能会连续测试不同问题不给清空上下文会混乱。为了提升演示观感我在聊天窗口里预设了几个推荐问题按钮“官网能做哪些定制”、“产品怎么接入”、“有免费试用吗”。点击按钮就能自动发送给出降低演示时对手动输入的打字依赖。这个细节在公开场合尤其加分。5. 实操中的问题与排查实录5.1 路由刷新404静态部署第一坑这个坑几乎人人会遇到使用HTML5 History模式路由后在本地服务上一切正常一旦放到静态服务器或演示环境刷新内页就404。原因很简单服务器在找不到对应文件路径时没有把请求回退到index.html。解决办法是在服务器配置一个fallback。比如在Nginx里location / { try_files $uri $uri/ /index.html; }如果是Vercel或Netlify需要加一个重写规则如vercel.json{ rewrites: [{ source: /(.*), destination: /index.html }] }演示前一定要记得在真实部署环境中测试刷新而不是只在本地路由点击跳转。我吃过这个亏一次现场演示时点了一个动态路由后手动刷新结果白屏场面很尴尬。5.2 Mock数据和CORS的联调问题开发阶段用mock很舒服但联调智能体接口的时候前后端一分开就遇到CORS问题。前端发请求到http://localhost:8000/api/chat控制台直接报跨域。我用FastAPI的CORSMiddleware解决了记得把allow_origins设成具体的开发地址不要用*因为浏览器在处理带凭证的请求时不允许。如果你用其他后端框架同理都要配置白名单。mock数据如果同时在vite和真实代理间切换我建议在vite.config.ts中根据环境变量动态决定是否启用mock。否则后端联调时mock拦截了请求你根本看不到真实返回。这个经验是demo阶段的mock不是给最终联调用的要设置开关。5.3 移动端适配与字体图标缺失官网demo往往优先在电脑浏览器演示但客户也可能用iPad看。我用了响应式断点768px、1024px。移动端最重要的改动是导航从水平排列变成抽屉首页Hero的文字缩小一档产品卡片变成单列。如果你没时间做全面适配至少保证在iPad竖屏下所有页面不横向滚动。字体图标缺失这个坑也很隐蔽我用了iconfont在开发环境正常但打包部署到服务器后图标全是方块。原因是没有引入正确的CSS或者字体文件路径用了绝对路径导致404。建议把字体文件也放入打包后的assets目录下使用相对路径引用。5.4 常见问题速查表问题现象可能原因快速处理方式刷新404History路由没有fallback配置服务器try_files或rewrite接口跨域报错前后端CORS未配置后端加白名单前端用代理浏览器打开HTML后接口全部404静态文件直接打开不经过vite代理启动开发服务器或用完整部署环境智能体回复很慢大模型推理延迟高给前端加loading动画并流式输出图片不显示路径用了绝对定位或打包后目录错误改为相对路径或import引入列表和详情页数据不同步组件复用导致onMounted不触发用watch监听路由参数重新加载数据移动端横向滚动固定宽度元素超出视口检查容器宽度max-width: 100%用百分比布局图标显示为方框字体文件加载失败或路径错误检查字体css路径使用CDN或本地打包6. 根据经验补几个小技巧最后再根据这次demo总结几个可能对你有帮助的点。做官网demo时不要把“演示”和“开发”完全割裂代码结构和真实官网尽量保持一致宁可多花半天改造也别在demo里写一堆硬代码。这样如果demo通过直接就能在此基础上继续迭代而不是推翻重写。关于那个“1”的亮点功能如果不知道加什么优先考虑“智能体问答”因为现在AI应用的门槛已经很低了只需一个接口就能跑起来。即便不用agno也可以用任何支持OpenAI兼容接口的SDK。这个功能不仅能在演示时制造惊喜还能引导访客快速获得产品关键信息。另外一定要在交付demo时写一个简短的README贴上启动命令、演示账号、建议提问话术。虽然这个东西看起来是程序员自嗨用的但领导和外部客户真的会照着README操作效果比你在旁边口头解释好太多。我也踩过几次坑后发现官网demo的成败其实不取决于技术多先进而在于页面信息有没有组织得清楚、交互是否顺滑、核心有没有让人“哇”一下的亮点。81的精髓不在数字上而在“1”——那点超出预期的东西才是让它被记住的理由。希望这篇对你也有点用。
阅读完成 · 觉得有帮助？
