先成功打开网站
- 把完整压缩包解压到一个容易找到的文件夹,例如
D:\PetSeatWebsite。不要在压缩软件预览窗口中运行网页。 - 推荐使用当前版本的 Edge / Chrome,并保持联网。
- 按照下方步骤启动预览服务,或打开已部署的网站地址;网页会自动连接配置好的 Sketchfab 模型。
- 点“标注与设置”核对标注清单;需要恢复 API 控制时,使用面板中的“重新连接模型”。
Windows:启动在线模型预览
- 先从 Python 官网安装 Python 3,或从 Node.js 官网安装 LTS。两者只需一个;安装后重新打开终端。
- 回到解压文件夹根目录,双击
start-preview.bat。它会启动本机 8080 端口,并打开浏览器。 - 在浏览器访问
http://127.0.0.1:8080。如果网页先于服务启动而报错,刷新一次即可。保持命令行窗口开着;关闭窗口会停止本地服务。
也可以在根目录地址栏输入 cmd 后回车,再执行:
py -3 -m http.server 8080 --bind 127.0.0.1 --directory public
如果只有 Node.js:
node tools/server.mjs
macOS / Linux
安装 Python 3 后,在项目根目录运行:
python3 -m http.server 8080 --bind 127.0.0.1 --directory public然后访问 http://127.0.0.1:8080。本地服务器只在电脑上预览,其他人通过互联网看不到;正式发布见第 8、9 章。
Airspace 的界面为什么能这样交互
对 参考站进行了实际浏览,观察了白天 / 夜晚、座椅状态和空间热点说明。当前页面引用了包含 Babylon.js 的 3D 脚本,没有 Sketchfab iframe。因此,它的机制是自有 3D 场景与网页界面共同工作;本网站按照你的要求改用 Sketchfab。
| 参考站元素 | 原理 | 你的版本 |
|---|---|---|
| 顶部 Logo | 网页图像层,与 3D 模型独立 | 本地 SVG / PNG,可独立替换 |
| 全屏客舱 | Canvas、相机和模型场景 | Sketchfab iframe 与官方 Viewer API |
| 底部图标 | 按钮事件触发灯光、动画或相机状态 | 01—04 对应真实标注;另有复位、模型已有动画、全屏 |
| 圆形加号热点 | 3D 空间位置与屏幕显示关联 | Sketchfab 原生标注点,可显示 / 隐藏 |
| 镜头飞入 + 深蓝说明 | 改变镜头,显示当前热点内容 | gotoAnnotation 移动镜头;本站卡片显示标题、正文 |
父页面与 Sketchfab 属于不同域名,浏览器不允许父页直接读写 iframe 内部界面。官方 SDK 通过消息通信提供模型控制。换按钮样式不需要修改模型;改变模型视角则需要调用 Viewer API。
本项目没有复制 Airbus 的品牌标志、字体、模型或原站代码。顶部为可替换的宠物客舱占位 Logo,图标为本地线稿。未为用户模型虚构日夜灯光和躺卧功能;播放按钮只播放模型已有动画。
文件结构:日常只改 00-replace
public 是可以直接发布的完整网页;dist 是构建得到的同类产物。日常修改 public 后直接上传 public;若要使用 dist,请先重新构建,避免上传旧版本。
| 路径(相对于 public) | 作用 | 何时修改 |
|---|---|---|
| 00-replace/site.config.js | 标题、Logo 路径、封面、作者、超时时间 | 更换品牌或页面信息 |
| 00-replace/brand/ | Logo、浏览器小图标 | 更换品牌素材 |
| 00-replace/icons/ | 底部及工具栏 SVG 图标 | 更换控件造型 |
| 00-replace/theme.css | 配色、Logo 大小、顶栏 / 底栏高度 | 调整视觉风格 |
| 00-replace/embed/embed.js | 完整 Sketchfab 嵌入代码 | 更换模型 |
| 00-replace/navigation/items.js | 导航顺序、图标路径、文案、标注映射 | 重新配对标注 |
| 00-replace/poster/ | 本地封面;默认是抽象占位图 | 替换为自己的产品渲染图 |
| assets/ | 核心 CSS、界面逻辑、映射、Sketchfab 适配 | 开发者扩展功能 |
| vendor/ | 本地第三方运行库与许可 | 一般无需改动,不要删除 |
| index.html / guide.html / sw.js | 网页、中文手册、旧版本升级清理脚本 | 布局与文档更新 |
根目录还有 tools(构建 / 检查 / 本地服务)、tests(映射测试)、deploy(服务器配置)、docs(分析与验证记录)。自编源码用中文注释;第三方库保留原作者语言与许可。
换 Logo、按钮和颜色
替换顶部 Logo
- 准备透明背景 SVG,或透明 PNG。建议横向画布约 440×100,四周留少量空白。
- 如果是 SVG,直接覆盖
00-replace/brand/logo.svg。 - 如果是 PNG,把它命名为
logo.png放入 brand,再修改site.config.js:
logo: './00-replace/brand/logo.png',
brandName: '你的品牌名称',在 theme.css 中调整 --logo-width: clamp(184px, 15vw, 264px);。手机与低矮横屏的尺寸也在 00-replace/theme.css 对应的媒体查询中集中调整。
替换底部控件
图标建议使用 28×28 SVG,透明背景、线条居中。可覆盖原文件,也可新增文件后在 items.js 修改 icon。PNG 也能使用。SVG 当前颜色写在图标文件的 stroke 上;改主题色不会自动改 SVG 内容,若需一致请同步修改图标色。
增加控件与整体居中
在 00-replace/navigation/items.js 的数组中复制一项,修改唯一的 id、显示编号 number、标题、图标与实际标注对应关系,项目顺序就是底部排列顺序。增加第 5 项时,先在 Sketchfab 创建并保存对应标注,再配置 annotationNumber: 5;缺少标注的按钮会禁用。
布局不绑定“四个控件”:#feature-nav 是居中的滚动视口,内部 #feature-nav-track 根据配置自动生成整个控件组。可完整显示时,整个按钮组对齐页面中心;数量增加后,超出的部分在这个区域横向滚动,首项与末项都可以访问,不会撑宽整页。
宽屏的左侧文字与右侧辅助操作占用相同宽度,避免把导航推偏;宽度不大于 1150px 时,导航独占上面一行,“标注与设置 / 使用指南”在下一行居中。低矮横屏保留紧凑高度,并在两侧预留等宽区域。
/* public/00-replace/theme.css:常用布局替换入口 */
--deck-side-width: clamp(132px, 14vw, 220px); /* 宽屏左右等宽区域 */
--nav-item-width: clamp(88px, 6.5vw, 116px); /* 每项宽度 */
--nav-gap: clamp(8px, 1.2vw, 24px); /* 项目间距 */
/* 手机和低矮横屏的覆盖值在同一文件下方。增加项目不需要修改核心 CSS。 */
替换配色与文字
/* 00-replace/theme.css */
:root {
--navy: #08294b; /* 深蓝:说明卡与主要文字 */
--accent: #007e8c; /* 青色:选中状态和链接 */
--accent-soft: #e8f5f5;
--stage: #f1f4f5; /* 模型区域背景 */
--logo-width: 202px;
}页面标题和项目说明在 site.config.js;说明卡正文在 items.js。当模型标注本身有正文时优先显示其正文,否则显示本站配置的说明。默认按钮名会在连接后用真实标注名更新;若要始终使用自定短标题,将 autoLabelFromAnnotation 改成 false。
要替换静态封面,把自己的渲染图放入 poster 文件夹,并同步修改 site.config.js 的 poster。默认封面是示意图,不是用户原模型的渲染图。
不同设备的展示与尺寸替换
页面使用设备的可视高度与安全区留白。模型区自动占据上下栏之间的空间;主要按钮保留至少 44 像素的触控高度。改变窗口尺寸或旋转设备不会由本站主动重载模型或重置镜头。
| 设备 / 窗口 | 布局行为 |
|---|---|
| 手机竖屏,宽度不大于 640px | 底部导航与辅助操作分为两行;视图工具横排;长标注正文在卡片内部滚动。 |
| 手机横屏 / 低矮窗口,高度不大于 500px 且宽高比至少 6:5 | 顶栏 52px、底栏 96px,隐藏装饰性旁文;导航和辅助操作并排,优先保留模型显示高度。 |
| 平板和一般电脑 | 宽度不大于 1150px 时导航独占一行并整体居中;更宽时使用左右等宽布局。设置面板头部保留、内容独立滚动。 |
| 大屏显示 | Logo、边距、导航项目宽度与字体在设定上下限内逐渐增大。 |
常用尺寸变量全部在 theme.css:--header-height、--footer-height、--logo-width、--gutter、--nav-item-width、--nav-gap、--deck-side-width、--dialog-margin。保留 --tap-target: 44px 与 --tool-size: 44px 可避免按钮变得难以点击。
导航项目变多时,可在导航区域左右滑动;程序也会将当前选中的标注按钮滚动到可见位置。较长按钮名称最多显示两行,完整名称仍保留在可访问标签和悬停提示中。手机显示单指旋转 / 双指缩放提示;设置表格会换行,避免撑宽整页。
上一版 1.2.0 已覆盖 320×480 到 2560×1440 的 13 种浏览器视口。当前 1.2.1 调整了底栏居中布局;本次浏览器预览因自动审批额度限制未能打开,因此本次视觉回归尚未验证。当前变更、已有验证记录与人工复核步骤见源码包 docs/responsive-validation.md。
更换 Sketchfab 模型
- 在 Sketchfab 打开你要展示的模型,确认能在目标浏览器中访问,并允许所需的外部嵌入。
- 使用模型的 Embed 功能复制嵌入代码。
- 用 VS Code 打开
public/00-replace/embed/embed.js,只替换两枚反引号之间的整段内容。 - 保存文件,通过本地服务器重新打开网页。点“标注与设置”,确认新的模型 ID 和标注清单。
- 同步修改 site.config.js 的作者信息、封面,以及 items.js 的标注对应关系。
/* 反引号里面粘贴你的完整嵌入代码;保留外层变量名。 */
window.SKETCHFAB_EMBED_HTML = `
<div class="sketchfab-embed-wrapper">
<iframe title="你的模型标题"
src="https://sketchfab.com/models/你的32位模型ID/embed?camera=0&annotations_visible=0"
allow="autoplay; fullscreen; xr-spatial-tracking" allowfullscreen></iframe>
</div>`;
代码会提取 iframe 的 src / title 和模型 ID,再用官方 SDK 初始化同一模型。粘贴代码中的署名段落不直接写入模型容器,网站页脚单独保留作者 / Sketchfab 链接;更换作者时应同步更新作者配置。原生播放器品牌展示仍按 Sketchfab 规则运行。
聊天中用于展示的 https\://、\<iframe、target="\_blank" 需要恢复为正常 HTML。本交付已清理这些转义。
普通 iframe 只能嵌入显示,无法凭空控制标注。本项目的“普通嵌入”按钮用于 API 无法连接时保留播放器;该模式会禁用外部标注控制,避免误导。
不需要填写 Sketchfab API Token。网页源代码对访问者可见,账号密码和密钥都不应放入配置。不要假设隐藏播放器控制就能绕过平台订阅限制。
把按钮和标注重新关联
当前模型的嵌入页面元数据包含以下 4 个标注。默认配置已按顺序对应;以后模型修改后,使用网站诊断面板再次读取。
| 网站按钮 | 模型标注 | annotationNumber | API index |
|---|---|---|---|
| 01 萌宠伴飞界面 | 01 萌宠伴飞界面 | 1 | 0 |
| 02 通风装置 | 02 通风装置 | 2 | 1 |
| 03 翻起式坐垫 | 03 翻起式坐垫 | 3 | 2 |
| 04 宠物观察窗 | 04 宠物观察窗 | 4 | 3 |
例:按钮 01 改为关联标注 03
打开 00-replace/navigation/items.js,把第一项改成:
{
id: 'feature-01', // 唯一 ID,其他按钮不可重复
number: '01', // 界面显示编号,不控制模型
title: '翻起式坐垫',
annotationNumber: 3, // 这里才是关联的模型标注编号
annotationTitle: '', // 留空表示按编号
icon: './00-replace/icons/seat.svg',
description: '你的自定义说明。'
}保存、刷新,再点按钮 01,程序将请求第 3 个标注,也就是 API 下标 2。配置中的 number 只决定显示;不要为了换标注而只修改显示编号。
更稳妥的方式:按唯一名称配对
annotationNumber: 3,
annotationTitle: '翻起式坐垫',当 annotationTitle 非空时,优先按真实名称精确匹配,编号作为便于阅读的记录。这能适应标注重排;标注改名后也要更新名称。同名标注会被视为歧义并禁用该映射;不要给多个标注起相同名称。
实际控制原理
// 等待 viewerready 后读取标注列表。
api.getAnnotationList(function(error, annotations) {
if (error) return;
// annotations 的第 0 项,对应你看到的标注 01。
});
// 将可读编号减 1:01 → 0;03 → 2。
const index = annotationNumber - 1;
api.gotoAnnotation(index, {
preventCameraAnimation: false,
preventCameraMove: false
}, function(error) {
// 成功后才更新界面;镜头使用 Sketchfab 中保存的标注相机。
});
// 模型里点击标注,网站也会同步高亮相应按钮。
api.addEventListener('annotationSelect', function(index) {
// 查找关联到这个 index 的导航项,更新说明卡。
});
在 Sketchfab 中创建或调整标注
- 进入自己模型的 3D Settings / 编辑界面,找到 Annotations。
- 创建标注,将热点放到目标位置,填写名称与说明,并保存该标注所需的镜头视角。编辑器版本不同,控件位置可能变化。
- 保存模型设置。回到本网站点“重新连接”,再打开“标注与设置”。
- 面板显示真实序号、名称和对应网站按钮;可以点击某行跳转,也能导出 JSON 清单。确认条数、名称、镜头都正确。
若只新增标注,不会自动新增网站按钮。复制 items.js 的一个对象,改为唯一 id、显示编号和新映射即可。可以多按钮关联同一标注;从模型反向同步时高亮第一个匹配项。未映射标注仍可通过模型原生热点查看。
嵌入参数 annotations_visible=0 只是默认隐藏标注点,不等于删掉标注;底部按钮仍可通过 API 选择标注。“标注与设置”的勾选框可以显示原生标注点。默认关闭原生说明气泡,使用本站说明卡;若想保留气泡,将 showNativeAnnotationPopup 改为 true。
这类网站的最佳上线配置
以你当前“Sketchfab 承载 3D、自己的网站承载界面”的方式,首选静态托管 + 自有 .com 域名 + VS Code。本站没有数据库、支付和后台业务,无需先买高配置服务器;模型流量主要由 Sketchfab 承担。服务器性能也不能直接消除播放器的模型面数或显卡瓶颈。
| 使用情况 | 推荐配置 | 原因 / 边界 |
|---|---|---|
| 作品展示、参赛、快速公开 | Cloudflare Pages 静态托管;自有 .com;VS Code | 直接上传文件,无须服务器维护;有免费计划。具体收费以服务商当前页面为准,域名 / Sketchfab 另计。 |
| 已买服务器,或希望自行管理网站 | 阿里云 / 腾讯云中国香港节点;2 核 2 GB、40 GB 以上 SSD、适合访客量的带宽;Ubuntu LTS + Caddy | 这是本项目的建议起步规格,不是服务商套餐承诺。模型由浏览器显卡渲染;带宽和地区连通性比升级 CPU 更关键。 |
| 主要面向中国内地访客的企业正式官网 | 内地轻量服务器 / 静态托管,完成适用的备案流程 | 发布前按服务商和当地规则办理;Sketchfab 的跨境加载仍需单独实测。 |
| 服务器上已有宝塔或 Nginx | 沿用现有面板;建立纯静态网站,上传 public 内容 | 不必为本页再安装 WordPress、PHP 或 MySQL。证书和网站根目录在面板配置。 |
域名建议选择自己品牌的 .com,可用 pet.你的域名.com 作为子域名。本文所有 example.com 只是示例,不代表已注册、可购买或属于你。注册时比较首年价格、续费价格、转出规则、隐私服务和 DNS 管理;不要只比较首年优惠。域名注册商不必与托管商相同。
Cloudflare Pages 单个静态文件上限为 25 MiB。本项目界面文件很小,适合上传;模型内容由 Sketchfab 提供,本站只需要上传网页、图标和配置文件。
中国内地服务器对网站备案有要求;非中国内地节点的该项服务商备案要求不同。中国香港不保证对所有内地网络都快,部署前应在实际访客网络测试。此处依照所列服务商官方文档说明,具体规则以发布时要求为准。
方案 A:不用买服务器,直接发布
1. 准备上传内容
- 先在电脑验证 public/index.html 和本地服务器模式。
- 将 public 里面的全部文件准备上传。上传包顶层必须直接看到 index.html、assets、00-replace、vendor 等。
- 不要上传整个开发项目代替网页目录;tools、tests、.git 都不是网页运行所需。
- 如果使用已构建的 dist,确认它与你修改后的 public 内容一致。不确定就直接上传 public。
2. 创建 Pages 项目
- 在 Cloudflare 控制台注册 / 登录并完成账户所需验证。购买、账户条款等由你自行确认。
- 进入 Workers & Pages,选择创建应用 / Pages,找到上传静态资产或 Direct Upload。若界面文案更新,选择官方教程中的直接上传方式。
- 给项目取一个英文名称,例如 pet-seat-showcase(仅为示例),上传准备好的文件夹或压缩包。
- 点部署,等待成功后复制平台返回的 pages.dev 地址。先打开临时地址验证,不急于绑定域名。
直接上传项目后续可以继续手动上传新版。官方文档说明:Direct Upload 项目不能直接切换成 Git integration;如需 Git 自动部署,创建新的 Git 集成项目。当前交付不要求你先掌握 Git。
3. 绑定域名
- 先注册好域名,在 Pages 项目的 Custom domains 中选择 Set up a domain,填入你的域名并按向导操作。
- 若使用根域名 example.com,需按 Cloudflare 要求将该域名加入账户并配置对应 nameservers。具体记录由平台生成。
- 若使用子域名 pet.example.com,可在现有 DNS 服务商添加 CNAME:主机记录
pet,目标填入平台实际分配的项目.pages.dev。 - 先在 Pages 关联域名,再配置 CNAME。只添加 DNS 记录而不在项目里关联,可能出现 522 等错误。
- 等待 DNS 和证书状态生效,使用 HTTPS 打开正式域名。不要自行猜测证书状态或绕过浏览器证书警告。
| 记录类型 | 主机 | 内容 | 用途 |
|---|---|---|---|
| CNAME | pet | 控制台实际返回的项目.pages.dev | 子域名连接静态托管 |
| NS | 注册商配置的域名服务器 | Cloudflare 实际分配的 nameservers | 根域名接入时按向导更换 |
4. 确认其他人能访问
用手机移动网络、另一台电脑和未登录你的账号的浏览器测试。网页打开成功后,还要确认 Sketchfab 模型对该访客可见。你的电脑已登录 Sketchfab 时能看见,不代表所有人都能看见。网站权限、模型权限和网络连通是三件独立的事。
方案 B:自己的服务器 + 域名 + HTTPS
以下面向一台新的 Ubuntu LTS 服务器;已有网站时不要覆盖现有服务或配置,可沿用原面板新建站点。你已拥有服务器和域名时,可直接从对应步骤开始。
1. 购买与连接
- 在阿里云或腾讯云选择适合访客地区的轻量服务器。当前嵌入式展示可从 2 核 2 GB 起步;不要因为 Sketchfab 原模型 200 MB 就直接购买很大的服务器内存。
- 选择 Ubuntu LTS 系统,记录公网 IPv4;设置 SSH 密钥或按服务商支持方式登录。密码和密钥不要写进网页源码。
- 在安全组 / 防火墙允许公网 TCP 80、443;SSH 22 仅按你的管理需要开放。不要给这类静态页面额外开放数据库端口。
- 在域名 DNS 控制台设置下表记录。若未配置 IPv6,不要添加无效 AAAA 记录。
| 类型 | 主机记录 | 值 |
|---|---|---|
| A | @ | 你的服务器公网 IPv4 |
| A | www | 同一公网 IPv4 |
| A | pet(可选) | 若希望用 pet.你的域名.com 则填写 |
2. 准备网站目录
通过服务商控制台的远程连接,或使用 SSH。以下以 root 登录做初次部署为例;其他管理员账号可在命令前使用 sudo。将 YOUR_SERVER_IP 替换为实际 IP,example.com 替换为你的域名。
# 在服务器执行:创建网页目录。
mkdir -p /srv/pet-seat
# 在你的电脑项目根目录执行:上传 public 里面的全部内容。
scp -r public/. root@YOUR_SERVER_IP:/srv/pet-seat/
# 回到服务器:确保网站进程可读取静态文件。
chmod -R a+rX /srv/pet-seat
# 检查:这里必须直接有 index.html,不应多套一层 public。
ls /srv/pet-seatWindows 可用系统 OpenSSH 的 scp,或使用可靠的 SFTP 客户端上传到相同目录。手动上传时打开 public 并全选其内容;服务器根目录应是 /srv/pet-seat/index.html。
3. 安装 Caddy
Caddy 可自动申请和续期 HTTPS。以下按照其官方 Debian / Ubuntu 安装方式;只需在新服务器初次安装时运行。已有 Nginx 占用 80/443 时,优先沿用 Nginx,不要让两个服务争用同一端口。
# 先更新软件索引,安装官方仓库所需工具。
apt update
apt install -y debian-keyring debian-archive-keyring apt-transport-https curl gnupg
# 加入 Caddy 官方签名和软件仓库。
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | tee /etc/apt/sources.list.d/caddy-stable.list
chmod o+r /usr/share/keyrings/caddy-stable-archive-keyring.gpg
chmod o+r /etc/apt/sources.list.d/caddy-stable.list
apt update
apt install -y caddy
4. 配置域名和 HTTPS
先备份现有 Caddyfile,再编辑。新服务器可将项目 deploy/Caddyfile 作为模板;将 example.com 与 www.example.com 改为自己实际配置的域名。
# 在服务器执行。
cp /etc/caddy/Caddyfile /etc/caddy/Caddyfile.backup
nano /etc/caddy/Caddyfile最小内容如下:
# 用实际域名替换;域名应已解析到此服务器。
example.com, www.example.com {
root * /srv/pet-seat
encode zstd gzip
@editable path / /index.html /sw.js /00-replace/*
header @editable Cache-Control "no-cache"
header X-Content-Type-Options nosniff
file_server
}在 nano 中按 Ctrl+O、回车保存,再 Ctrl+X 退出。然后:
# 检查配置无误后重载服务。
caddy validate --config /etc/caddy/Caddyfile
systemctl reload caddy
systemctl enable caddy
systemctl status caddy --no-pager如果服务器启用 UFW,可按实际需要执行 ufw allow 80/tcp 与 ufw allow 443/tcp;云平台安全组也要同时放行。Caddy 获取公开证书需要有效域名解析、80/443 可达、服务可绑定端口,以及持久可写的证书数据目录。
5. 验证网站
# 查看你的域名是否指向正确服务器;没有 dig 时可用 nslookup。
nslookup example.com
# 返回 HTTP 200 且证书正确,才表示基础访问正常。
curl -I https://example.com
# 查看服务日志,排查证书 / 权限 / 端口问题。
journalctl -u caddy -n 80 --no-pager用真实浏览器打开 HTTPS 域名,再测试模型与四个功能点。模型通过 Sketchfab 在线加载。更换网站服务器不会直接减少模型面数或浏览器显存需求。
已有 Nginx / 宝塔的情况
使用 deploy/nginx.conf 的 HTTP 示例建立静态站点,根目录指向 /srv/pet-seat,上传后先验证。通过控制台证书功能或 Certbot 按域名签发证书,再启用 HTTPS / HTTP 跳转。该示例未内置你的证书路径,不能把它当作已经配置好 HTTPS 的成品。静态站点无需 PHP 项目、数据库或 Node.js 常驻进程。
发布后的更新、备份与回滚
- 先备份:复制当前完整网页目录,按日期命名。嵌入配置、导航配置、Logo 一起保留;不要只备份 index.html。
- 先本地验证:编辑 public/00-replace,启动本地服务,检查按钮、标注和移动端。
- 再上传:Pages 创建新部署;服务器覆盖对应网页文件。修改模型 ID 时要同时更新映射、封面和作者。
- 刷新缓存:先使用 Ctrl+Shift+R。修改 public 后直接上传当前文件;使用 dist 时先运行 npm run build,避免上传旧产物。
- 回滚:托管平台回到上一部署版本,或将服务器备份重新上传。回滚后关闭旧标签并重新打开,避免页面继续显示旧状态。
当前版本的 sw.js 仅用于清理旧版本的本站缓存并注销原有 Worker,不拦截请求、不写入资源缓存。网页展示需要网络连接;升级后可按 Ctrl+Shift+R 重新载入。
开发者重建命令
# 无第三方构建依赖;将当前 public 复制为 dist。
npm run build
npm run check
npm test
# 本地预览 public。
npm run dev本版本使用 Node.js 内置模块,无需安装第三方构建依赖。日常素材替换后只上传 public 内容即可;dist 由 build 生成。
常见问题与处理顺序
| 现象 | 优先检查 | 处理 |
|---|---|---|
| 网页空白 / 缺图 | 是否只复制 HTML,是否仍在压缩包中,路径大小写是否一致 | 完整解压;使用 public;启动本地服务;检查 00-replace 和 vendor 是否齐全 |
| 模型一直加载 | 直接打开原始 Sketchfab 嵌入地址是否成功 | 先排除模型权限、平台访问和网络;网站提示超时后检查网络并重试,也可使用普通嵌入 |
| 播放器说 can't be displayed | WebGL、硬件加速、模型体量、设备显存、平台实际错误 | 换合适设备实测;检查浏览器硬件加速;减少模型面数 / 纹理;不能仅凭此提示认定为服务器问题 |
| 按钮变灰 | API 未就绪,普通嵌入模式,或配置关联的标注不存在 | 打开“标注与设置”查看状态;恢复 API 连接;重新核对编号 |
| 01 跳错位置 | 模型标注重排,或该标注本身保存了错误镜头 | 按真实名称关联;或去 Sketchfab 保存正确视角 |
| 标注点看不见 | 原始嵌入参数 annotations_visible=0 | 在设置中勾选“显示原生标注点”;隐藏点不代表不存在标注 |
| 只能改底栏,改不了播放器 Logo | 跨域 iframe 和平台能力限制 | 在 Sketchfab 设置允许的范围内调整;父页 CSS 无法直接改播放器内部 |
| 动画按钮灰色 | 模型没有可读取的动画,或尚未完成连接 | 先确保 Blender 已正确导出动画,模型在平台中能播放 |
| 8080 端口被占用 | 旧预览窗口是否仍在运行 | 关闭旧服务,或把命令的 8080 改成 8081,并访问新端口 |
| 域名打不开 / 证书错误 | DNS A/CNAME、是否绑定平台、80/443、防火墙、证书状态 | 先验证托管临时地址或服务器;核对解析;完成 HTTPS,不绕过证书警告 |
| 换素材后没更新 | 是否上传了旧 dist,是否命中缓存 | 直接发布当前 public;强制刷新;关闭旧标签后重开,确认上传的是当前文件 |
当前模型公开元数据约 682 万面、17 张贴图、43 个材质、1 段动画。这是本次读取时的快照,不代表传输文件的 MB 数,不能仅凭面数推断文件大小。若移动端体验较慢,优先减少不必要的高密度几何、重复材质和大纹理,另做轻量展示版本。
上线前的验收方法和本次验证边界
- 电脑与手机都能看到顶部 Logo、模型区和底部按钮,窄屏底栏可滑动,文案不遮住关键区域。
- 在线模型成功连接后,诊断清单能显示四个实际名称;点 01—04 分别跳到对应标注;在模型中点标注,底栏同步高亮。
- 复位回到初始镜头;动画播放 / 暂停可用;无动画时按钮合理禁用;全屏可进退。
- 断网时给出网络提示;恢复网络后,重新连接模型以继续展示。
- 在另一台未登录你的账号的设备与移动网络上验证正式 HTTPS 域名,以及 Sketchfab 模型访问权限。
- 实际核对所有作者、品牌、说明文案、域名和可公开范围。
关于当前原始 Sketchfab 模型:已从你提供的嵌入页面中核对四项标注元数据与顺序,并据此写入默认配置。当前测试浏览器未提供 WebGL,直接运行原始播放器时显示“Sorry, the model can't be displayed.”。因此,这次不能声称该真实模型的相机跳转和动画已在测试浏览器端到端通过;也不能由此断定你的电脑会失败。
当前版本的界面、配置和关联检查以 docs/validation.md 为准。诊断面板会在可连接环境读取 API 清单,便于核对实际标注。
进一步参考的官方资料
文档核对日期:2026-11-16。平台控制台、套餐和收费可能更新,实际发布以当前官方页面为准。