可视化 Web AR 构建器 (标记追踪版)— 使用说明

可视化 Web AR 构建器 — 使用说明书

零代码搭建 AR.js 多标记追踪场景。4 步从空白到部署上线。

版本说明（请先读这一段）

当前版本没有的功能：自然图片识别（NFT）、GPS/户外定位、无标记的空间追踪。这些能力会放在后续版本中，不在本版本内。

目录

1. 快速上手（4 步）
2. 界面一览
3. 标记管理
4. 添加内容
5. 属性面板详解
6. 场景参数与追踪平滑
7. 实时预览
8. 导出项目包
9. 免费版与专业版
10. 部署上线
11. 微信分享配置
12. 项目保存与打开
13. 常见问题
14. 最佳实践

1. 快速上手（4 步）

第 1 步：添加标记

左侧面板 → 标记设置 → 点击「＋ 添加标记」。

构建器会自动完成三件事：

1. 随机生成一个唯一图案（.patt 文件，每个标记必须不同）
2. 生成可打印的标记图（带识别图案 + 编号）
3. 配置好 pattern 与默认尺寸

点击标记卡片里的「⤓ 下载标记图」保存图片，打印出来（边长建议 ≥10cm，亚光纸 + 哑光膜，避免阳光直射反光）。

第 2 步：填写标记尺寸

标记卡片里的「标记尺寸（米）」字段，填打印出来的实际边长。

⚠️ 这步很关键！填错了 AR 里的内容比例会严重失真。比如你打印的标记是 15cm 边长，就填 0.15。

第 3 步：添加内容

中间面板 → 点击「＋ 添加内容」→ 选择类型（共 4 种：图片 / 视频 / 音频讲解 / GLTF 模型）。

添加后在右侧属性面板把它归属到对应标记（选择「归属标记」下拉）。

第 4 步：导出部署

右上角 → 「导出项目包」→ 填写访问地址和项目图标 → 导出 ZIP。

ZIP 里的 xxxxar/ 目录上传到任意 HTTPS 服务器，用手机访问即可；包根目录的标记图打印后贴到现场。

2. 界面一览

界面分三栏，顶部是工具栏：

左侧面板：场景配置

• AR 模式：当前仅「标记追踪」（Multi Marker 3D）
• 场景参数：渲染器设置（抗锯齿 / 透明背景 / 对数深度缓冲）、摄像头源
• 标记设置：快速上手提示 + 标记列表 + 追踪平滑

中间面板：场景内容

• 顶部「＋ 添加内容」按钮打开类型选择弹窗
• 内容列表展示所有已添加的内容（可点击选中编辑）
• 下方 tab 切换：实时预览（3D 渲染，拖动旋转 / 滚轮缩放）/ 生成代码（查看导出 HTML 源码）

右侧面板：属性编辑

• 未选中内容时显示空状态提示
• 选中内容后显示：名称、归属标记、位置 / 旋转 / 缩放、类型特有属性

3. 标记管理

添加标记

点击「＋ 添加标记」，构建器自动生成图案和标记图。最多 20 个标记（面板右上角显示 n / 20）。

标记卡片字段

删除标记

点标记卡片右上角的 ×。删除标记会把归属到该标记的所有内容一并清除。

4. 添加内容

点击中间面板顶部的「＋ 添加内容」，弹窗里有 4 种类型：

🖼 图片

• 上传 PNG/JPG 图片（构建器内保存为资源，导出时写入 assets/）
• 适合海报、指示牌、设备铭牌
• 导出后是一块贴在标记上的平面

▶ 视频

• 上传 MP4/WebM 视频
• 识别到标记后出现，带播放控制条（播放 / 暂停 / 进度）
• 适合产品演示、宣传片

🔊 音频讲解

• 上传 MP3/WAV 音频
• 识别到标记自动播放，标记离开画面自动停止，支持音量调节
• 适合展厅语音导览、设备说明

💡 音频播放条件：浏览器要求音频必须在用户手势（触摸/点击）中解锁。所以第一次打开 AR 页面时，在屏幕上点一下就解锁了。

◆ GLTF 模型

• 上传 GLB/GLTF 格式模型（推荐单文件 .glb）
• 可勾选「播放模型内置动画」
• 真机显示姿态可通过「真机朝向校正 X」微调（默认 -90°）
• 适合产品拆解、工业设备展示

💡 建议模型面数 ≤ 5 万、文件 ≤ 10MB，手机性能有限。

本版本没有「文字」类型，需要文字请做成图片上传。

5. 属性面板详解

选中内容后右侧属性面板显示：

公共字段（所有类型都有）

类型特有字段

图片 / 视频

音频讲解

• 音量：0 ~ 1

GLTF 模型

6. 场景参数与追踪平滑

场景参数（左侧面板）

追踪平滑（左侧面板）

AR.js 识别标记的坐标会抖动，平滑让它看起来更稳定。

7. 实时预览

中间面板下方切到「实时预览」：

• 拖动：旋转视角；滚轮：缩放
• 左上角提示条显示当前内容的实际尺寸（例：图片 1 · 3.51 × 3.00 × 1.92 ×识别图宽）
• 白色虚线框 = 标记识别图的原尺寸参照（宽 1 单位）
• 红色 = X 轴，蓝色 = Z 轴，边缘刻度 0.1
• 「视角」下拉可切换查看全部点位或单个点位

预览是 A-Frame 简化渲染，主要用来确认相对位置 / 比例 / 排版，最终效果以真机为准。切到「生成代码」可以查看即将导出的 HTML 源码。

💡 预览里上传的本地图片/视频以资源地址（blob:...）显示，属正常现象；导出后会自动改成 assets/xxx 路径。

8. 导出项目包

右上角「导出项目包」打开设置弹窗：

二维码只在 ZIP 里生成一张 PNG（印在海报/展板上用），不会显示在 AR 页面里。

ZIP 目录结构

<项目标题>.zip
├── 202611041530ar/          ← 上传服务器用这个目录
│   ├── index.html
│   ├── libs/                ← A-Frame、AR.js、免费版核心模块
│   ├── assets/              ← 上传的图片/视频/音频/模型、标记图案
│   └── favicon.png          ← 项目图标（选了才生成）
├── markers/                 ← 线下物料（不用上传）
│   ├── 1 号车间 · 设备 A.png
│   ├── 2 号展厅 · 导览牌.png
│   └── 打印图对应表.txt      ← 点位名称 / 文件名 / 边长
├── 项目二维码.png            ← 填了访问地址才生成
├── 项目信息.txt
└── 使用说明.txt

⚠️ xxxxar/ 目录里的文件必须整体上传、不要改名，index.html 按文件名引用 libs/ 和 assets/。

9. 免费版与专业版

注册专业版

1. 点右上角「免费版｜点击注册」，打开注册对话框
2. 复制机器码发给管理员
3. 收到注册码后填入，点「注册」（需联网校验一次）
4. 成功后按钮变为「专业版」，导出的项目不再带水印

💡 机器码与当前电脑绑定。更换电脑/重装系统后机器码可能变化，需要重新获取注册码。
注册状态会缓存，断网时按上次在线校验结果在有效期内继续使用。

10. 部署上线

上传什么

只上传 ZIP 里的 xxxxar/ 整个目录（markers/、二维码、说明文件属于线下物料，留在本地）。

方式 1：自建 HTTPS 服务器

把 xxxxar/ 放到 Nginx/Apache 的静态目录下，确保通过 HTTPS 访问。

方式 2：ngrok 临时测试

python -m http.server 8080
ngrok http 8080
# 拿到 https://xxxx.ngrok.io 这个地址就是访问地址

方式 3：静态托管

Vercel / Netlify / Cloudflare Pages — 把 xxxxar/ 目录拖上去，自动给 HTTPS 域名。

测试流程

1. 用手机访问部署后的 HTTPS 地址
2. 页面加载后点一下屏幕（解锁音频）
3. 把打印好的标记图对准摄像头
4. 标记识别成功 → 内容出现 → 音频自动播放

11. 微信分享配置

导出的 HTML 已自动包含 Open Graph 标签，微信分享时展示标题 + 描述 + 图片。

验证

把地址发到「文件传输助手」，在聊天里点开 → 分享给朋友，即可看到分享卡片效果。

不生效怎么办

1. og:image 没图：确认服务器上 https://域名/.../favicon.png 真实可访问
2. 还是旧内容：微信缓存，加参数强制刷新 — https://your-domain.com/ar?v=2
3. 只有链接没有卡片：域名首次需要微信爬虫访问一次

12. 项目保存与打开

保存项目

工具栏「保存项目」→ 保存为 .arproj 文件（本质是 JSON，包含全部标记、内容、属性与上传素材）。

打开项目

工具栏「打开项目」→ 选择 .arproj 文件 → 恢复所有标记、内容、属性。

💡 关闭窗口后内存里的内容就没了，关软件前记得保存。

13. 常见问题

Q1：手机扫描识别不到标记

1. 确认打印清晰度：图案线条不能断，边缘要锐利
2. 确认光照：不要直射标记，柔和漫射光最好
3. 确认标记图案没有被弯曲/遮挡
4. 试一下重新生成标记（注意：重新生成后旧打印图失效）

Q2：识别到了但内容比例不对

99% 是标记尺寸填错了！ 回去看标记卡片里的「标记尺寸（米）」，填打印出来的实际边长。15cm → 填 0.15。

Q3：音频不播放

• 第一次打开页面先点一下屏幕（浏览器安全策略）
• 确认素材已上传成功（属性面板「素材」字段有地址）
• 服务器上确认 assets/ 里有对应文件

Q4：视频不播放

• MP4 必须是 H.264 编码
• 文件不要太大（建议 ≤ 30MB）
• 服务器要支持 range 请求（Nginx 默认支持）

Q5：3D 模型加载不出来 / 躺倒

• 必须是 .glb 单文件格式
• 文件 ≤ 10MB、面数 ≤ 5 万
• 模型躺倒时调整「真机朝向校正 X」（默认 -90°）

Q6：微信里打开页面摄像头权限被拒

必须是 HTTPS！ HTTP 域名在微信里不能调用摄像头。本地测试用 ngrok。

Q7：识别提示文字在哪显示

手机识别到标记后，AR 画面会自动弹出说明面板（标题 + 说明，就是标记卡片里填的内容）。留空则不弹。

Q8：实时预览里图片显示成资源地址 / 内容位置不对

预览是 A-Frame 简化渲染，主要看相对位置与比例；资源地址显示 blob:... 属正常，导出后自动替换为 assets/ 路径。

Q9：部署后资源找不到（404）

• 有没有把 xxxxar/ 整个目录上传（漏了 libs/ 或 assets/ 就会 404）
• 放在子目录时，访问地址要填完整路径（如 https://domain.com/ar/）

Q10：导出的项目能改吗？

可以，但免费版不要删除 libs/ 里的核心模块（ar-core.xxxx.js）：删掉后摄像头不会启动、标记也不会识别（页面会白屏）。需要无水印、可自由修改的版本请注册专业版。

Q11：点窗口右上角 × 后程序直接退出了

这是正常行为：关闭窗口即退出程序。请养成先「保存项目」再关闭的习惯。

14. 最佳实践

标记设计

• 图案不要重复：每个标记用不同 pattern，构建器已自动随机生成
• 色彩对比强：黑白对比，不要做彩色
• 避免反光：亚光纸 + 哑光膜
• 尺寸够大：边长 ≥ 10cm，远距离识别更稳

内容组织

• 复杂场景拆项目：超过 20 个点位时分多个项目，分别导出部署
• 音频做讲解，视频做演示：音频是空间感知的，视频是平面展示
• 图片优先：能说清楚就别上视频，移动端流量和性能都吃紧

性能

• 模型 ≤ 10MB / 面数 ≤ 5 万
• 视频 ≤ 30MB / H.264 编码
• 图片用 WebP/PNG-8 压缩

部署

• 用静态托管（Vercel/Netlify/Cloudflare Pages）最省事
• 上线前真机完整走一遍：扫码 → 识别 → 播放 → 切后台再回来
• 分享卡片先验证再发给用户

文档版本：v1.1 | 更新日期：2026-11-04 | 适用版本：构建器 v1.0（标记追踪版）