Three.js让东坡开口念定风波:诗词页踩坑实录

基于 WorkBuddy 搭配 Hy4 Preview 打造「苏轼《定风波》三维诗词页」:Three.js + Web Speech API 从 AI 建模到网页朗读的完整实践 > 摘要 :本文记录了在 WorkBuddy + Hy4 Preview 环境下完成的一个有趣的跨界实践——用腾讯混元生 3D 生成苏轼的三维人像,再用 Three.js 把它搬进网页,最后调用浏览器原生的 Web Speech API,让东坡先生"亲口"念出《定风波》。全文围绕模型生成 → 结构校验 → 场景搭建 → 加载容错 → 竖排排版 → 语音同步 六个环节展开,重点复盘了"内联模型解析失败"这一真实踩坑的完整排查过程,并给出可复用的排查思路与最终方案。所有代码均可直接运行。

开发环境 :WorkBuddy(Windows 客户端)+ Hy4 Preview

关键词 :Three.js、Web Speech API、GLTFLoader、混元生3D、GLB、竖排排版、语音合成

阅读建议 :假如你只关心"怎么让网页朗读中文并高亮",可直接跳到第五章;如果你正在被"GLB 算法加载失败"折磨,第三章的排查思路会更有价值。 * * * ### 表现预览 先看看最终做成了什么样:一个浅色水墨风的页面,左侧是缓缓旋转的苏轼三维立像,右侧竖排展示《定风波》全文,底部是语音控制条。点击"朗读",页面会用中文逐句念出这首词,当前朗读的句子会实时高亮成红色 。

模型文件别内联进 HTML:base64 会让体积膨胀约 33%,51MB 的 glb 直接把解析内存顶爆;放到同域目录用 fetch 分段加载才稳。语音高亮别指望 boundary 事件,中文合成经常不触发,按句拆分逐句 speak 才可靠。
在这里插入图片描述

在线交互能力一览: 交互| 操作方式 ---|--- 旋转人像| 鼠标左键拖拽 缩放| 滚轮 平移| 鼠标右键拖拽 朗读全词| 点击"朗读"按钮 / 空格键 从指定句朗读| 直接点击该诗句 暂停 / 继续| 点击"暂停" / 空格键 停止| 点击"停止" / Esc 键 换音色 / 调速| 底部下拉框与滑块 手动载入模型| 点击选择文件,或把 glb 拖进页面 * * * ### 本文大纲 章节| 主题| 关键内容 ---|---|--- 一| 能力选型与整体结构| 为什么是 Three.js + 原生 Web Speech,整体模块划分 二| 三维人像:从 AI 建模到 GLB 校验| 混元生 3D 调用、GLB 二进制结构解析、扩展检查 三| 踩坑实录:51MB 内联模型的解析失败| base64 内联的陷阱、Node 环境复现、fetch 套路改造 四| 词文呈现:竖排排版与响应式| writing-mode 实战、视觉风格、移动端适配 五| 让东坡开口:语音朗读与高亮同步| speechSynthesis 逐句调度、中文嗓音筛选、GC 坑 六| 完整源码、运行与扩展| 项目结构、启动方式、换诗词/换人物的改造点 * * * ### 一、技术选型与整体架构 #### 1.1 要求拆解 最初的要求只有一句话:"做一个网页,展示苏轼的 3D 形象,配上他的代表作《定风波》,还能朗读出来。

"拆开看是三件事: 1. 三维内容从哪来 —— 手头没有任何苏轼的 3D 模型资产; 2. 怎么在网页里展示 —— 得 WebGL 渲染与交互控制; 3. 怎么"发音" —— 不引入后端 TTS 服务的前提下,最轻量的方案是什么。 #### 1.2 选型决策 要求| 候选方案| 最终选择| 理由 ---|---|---|--- 3D 模型来源| 手工建模 / 素材站下载 / AI 生成| 腾讯混元生 3D| 一句话出模,自带 PBR 纹理,无需美术基础 渲染引擎| Babylon.js / Three.js| Three.js r128| 生态最成熟,GLTFLoader 与 OrbitControls 开箱即用 语音合成| 云端 TTS API / 原生 Web Speech| Web Speech API| 零后端、零密钥、零费用,前端一个 API 搞定 交付形态| 多文件工程 / 单文件 HTML| 单文件 HTML| 双击即开,便于传播 这里有个值得说明的取舍:为什么不用云端 TTS 。

阿里云、腾讯云的语音合成表现确实更自然,但意味着要引入密钥管理、后端代理、跨域与计费。而 Web Speech API 尽管音色依赖用者操作系统自带的语音包(Windows 上一般是 Microsoft Huihui / Yaoyao),但零依赖、零成本 ,对一个展示型页面彻底够用。 > 关于研发环境 :本文的全部工作——从调用混元生 3D 生成模型、编写 Three.js 与语音代码,到第三章那场"解析失败"的排查——均在 WorkBuddy(Windows 客户端)+ Hy4 Preview 中经由对话完成。利器在这里的价值不在于替代思考,而在于把"假设 → 验证 → 修正"的循环压缩得足够短。

#### 1.3 架构分层 整个页面按"数据—呈现—交互"三层组织,最终经由构建脚本合并为单文件: ┌─────────────────────────────────────────────┐ │ 数据层 POEM[] 词文数组(展示/朗读共用) │ ├─────────────────────────────────────────────┤ │ 呈现层 Three.js 场景 + 竖排 DOM 词文 │ ├─────────────────────────────────────────────┤ │ 交互层 OrbitControls + speechSynthesis │ └─────────────────────────────────────────────┘ ↓ build_poem.py 内联合并 dingfengbo.html(751 KB,离线可用) 关键设计是词文只有一份数据源 。词句既要渲染成 DOM,又要送给语音引擎,要是各写一份,改一个标点就会不同步。于是统一用 POEM 数组,DOM 由它生成,朗读也按它的下标推进: var POEM = [ "莫听穿林打叶声,", "何妨吟啸且徐行。", "竹杖芒鞋轻胜马,", "谁怕?

一蓑烟雨任平生。", "料峭春风吹酒醒,", "微冷,山头斜照却相迎。", "回首向来萧瑟处,", "归去,也无风雨也无晴。" ]; * * * ### 二、三维人像:从 AI 建模到 GLB 校验 #### 2.1 用混元生 3D 生成苏轼像 模型借助腾讯云 ai3d 接口生成,核心参数如下: * 模型版本 :3.1(高精度) * 开启 PBR :生成自带金属度/粗糙度的物理材质 * 面数 :30 万 * 耗时 :约 3 分 35 秒 提示词是效果的关键。落地发现,描述越具体,出模越稳 ,尤其是"全面人体比例"“站立姿态”"纯色简洁背景"这类约束对生成质量影响很大: 中国古代北宋大文豪苏轼的写实风格全身立像,头戴黑色东坡巾,面容清癯、长须飘然, 神态儒雅从容,身穿宋代文人宽袖交领长袍,腰间束带,双手拢袖自然垂于身前, 双脚着布鞋,完整人体比例,站立姿态,精细的布料与皮肤纹理, 纯色简洁背景,适合三维展示

在这里插入图片描述

生成完成后务必第一时间把模型下载到本地 ——云端的 COS 链接一般只有 24 小时有效期。

最终拿到 models/sushi.glb。 #### 2.2 GLB 结构校验:先确认文件没坏 在怀疑任何加载代码以前,先验证文件本身。GLB 是二进制容器,结构非常规整:12 字节文件头 + 若干 chunk。 import struct, json data = open("models/sushi.glb", "rb").read() # 1) 校验文件头 magic, ver, length = struct.unpack("<4sII", data[:12]) print("magic:", magic, "version:", ver, "declared:", length, "actual:", len(data)) # 2) 遍历所有 chunk off = 12 while off < len(data): clen, ctype = struct.unpack("b'glTF'**,否则文件根本不是 GLB(可能是下载成了 HTML 错误页); 2. declared 与 actual 长度必须一致 ,不一致说明下载被截断; 3. 检查extensionsRequired 里有没有 KHR_draco_mesh_compression。如果有,GLTFLoader 必须额外挂载 DRACOLoader 并指定解码器路径,否则会直接报解析失败——这是最常见的"模型加载不出来"原因之一。

本例幸运地没有用 Draco,纹理也是内嵌 PNG,属于最省心的情形。 #### 2.3 搭建 Three.js 场景 场景部分追求"展厅感":柔和的环境光打出整体亮度,一盏主光投射柔和阴影,再补一盏冷色轮廓光把人物从背景里"抠"出来。 var scene = new THREE.Scene(); scene.background = new THREE.Color(0xf5f2ec); // 宣纸底色 var camera = new THREE.PerspectiveCamera(45, innerWidth / innerHeight, 0.01, 100); camera.position.set(0, 1.15, 4.3); var renderer = new THREE.WebGLRenderer({ antialias: true }); renderer.setPixelRatio(Math.min(devicePixelRatio, 2)); renderer.setSize(innerWidth, innerHeight); renderer.outputEncoding = THREE.sRGBEncoding; // 关键:否则 PBR 贴图会发灰 renderer.shadowMap.enabled = true; renderer.shadowMap.type = THREE.PCFSoftShadowMap; document.body.appendChild(renderer.domElement); var controls = new THREE.OrbitControls(camera, renderer.domElement); controls.enableDamping = true; controls.dampingFactor = 0.08; controls.target.set(0, 1.0, 0); controls.autoRotate = true; controls.autoRotateSpeed = 1.0; controls.minDistance = 1.5; controls.maxDistance = 12; // 三点布光:环境光 + 主光(投影)+ 冷色轮廓光 scene.add(new THREE.HemisphereLight(0xffffff, 0xbfae93, 0.85)); var key = new THREE.DirectionalLight(0xffffff, 1.05); key.position.set(3, 6, 4); key.castShadow = true; key.shadow.mapSize.set(2048, 2048); key.shadow.bias = -0.0004; // 消除阴影痤疮 scene.add(key); var rim = new THREE.DirectionalLight(0x9fb9c9, 0.35); rim.position.set(-4, 3, -3); scene.add(rim); 几个容易忽略的细节: * outputEncoding = sRGBEncoding 是 PBR 材质色彩正确的前提,漏掉会导致模型整体发灰、发闷; * shadow.bias 必须给一个小的负值,否则模型表面会出现条纹状的"阴影痤疮"; * shadow.camera 的 left/right/top/bottom 要覆盖模型包围盒,否则阴影会被裁掉。

#### 2.4 自动构图:让任意模型都居中且大小合适 AI 生成的模型尺寸是未知的,硬编码相机距离必然会翻车。正确做法是算出包围盒,再归一化缩放并居中 : function frameModel(obj) { obj.traverse(function (o) { if (o.isMesh) { o.castShadow = true; o.receiveShadow = true; } }); var box = new THREE.Box3().setFromObject(obj); var size = box.getSize(new THREE.Vector3()); var center = box.getCenter(new THREE.Vector3()); var maxDim = Math.max(size.x, size.y, size.z) || 1; var scale = 2.4 / maxDim; // 统一归一到 2.4 个单位高 obj.scale.setScalar(scale); // 先把几何中心移到原点,再抬高,使脚底落在 y = 0 的地面上 obj.position.sub(center.multiplyScalar(scale)); obj.position.y += (size.y * scale) / 2; scene.add(obj); } 这段逻辑的核心在于顺序 :先缩放、再平移中心、最终抬升。写反了算法会"陷进地里"抑或悬空。

在这里插入图片描述

      • 三、踩坑实录:内联模型的解析失败之谜 这一章是整个项目最有价值的部分 ,也是我踩得最狠的一个坑。

#### 3.1 起因:追求"真正的单文件" 最初的思路很朴素:既然要"双击就能打开",那就把 GLB 以 base64 编码直接内联进 HTML。于是生成了一个HTML 文件(37.7 MB 的 GLB 编码后膨胀约 33%)。 结果浏览器无情报错: 模型解析失败 #### 3.2 第一层排查:文件真的完整吗? 遇到"解析失败",第一反应是文件坏了。于是做了两件事: (1) 校验 base64 能否无损还原 import re, base64, hashlib html = open("sushi.html", "rb").read().decode("utf-8", "ignore") b64 = re.search(r'const GLB_B64\s=\s"([^"]+)"', html).group(1) data = base64.b64decode(b64) orig = open("models/sushi.glb", "rb").read() print("decoded bytes :", len(data)) print("orig bytes :", len(orig)) print("identical :", data == orig) print("sha256 (dec) :", hashlib.sha256(data).hexdigest()[:16]) print("sha256 (orig) :", hashlib.sha256(orig).hexdigest()[:16]) 输出 identical: True,两个 sha256 完全一致。文件毫无痛点。 (2) 用 Node 复现真实报错 既然文件没坏,就让同版本的 GLTFLoader 在 Node 里跑一遍,把真实异常抓出来: const fs = require('fs'); global.THREE = require('three'); require('three/examples/js/loaders/GLTFLoader.js'); const data = fs.readFileSync('models/sushi.glb'); const ab = data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength); new THREE.GLTFLoader().parse(ab, '', (gltf) => console.log('PARSE OK, children =', gltf.scene.children.length), (err) => console.error('PARSE ERROR >>>', err && err.message) ); 结果是 PARSE OK ——几何和材质都成功解析了!

结论 :模型格式与 r128 完全兼容,问题不在文件,而在浏览器端"51MB 巨型内联脚本 + atob"这条加载路径 。超大内联脚本在解析成 JS 字符串时,会撞上浏览器的内存与字符串长度上限,最终触发 parse 的失败回调。 #### 3.3 第二层排查:一个"假阳性"的干扰 排查过程中还遇到一个很有迷惑性的干扰,值得单独记一笔。我用一个命令检查 HTML 里是否还有未替换的placeholder: grep -c "THREE|APP|GLTF|ORBIT" sushi.html # 输出:1 看起来"还有一个placeholder没替换"。但实际上这是误报 :three.min.js 是压缩后的单行代码,整段挤在 HTML 的第 80 行;而它源码内部本身就含有 THREE 这个字符串(UMD 全局名判断)。

grep -c 统计的是匹配的行数 ,不是匹配次数,所以只要这一行里有这个串,结果即是 1。 教训 :用 grep -c 做完整性校验时,要注意它数的是行而非次数;压缩后的单行文件会让这类检查彻底失真。正确的做法是校验"裸露placeholder"这种带上下文的模式: grep -c "THREE" sushi.html # 这才是真正想查的 #### 3.4 最终方案:放弃内联,改用 fetch 方向很明确——别把 37MB 塞进 HTML 。改造后的方案: 对比项| base64 内联(失败)| fetch 加载(采用) ---|---|--- HTML 体积| 51 MB| 751 KB 首屏解析压力| 极大,易触发内存上限| 正常 双击打开| 可用| 受限于 file:// 安全策略 模型加载| 同步可用| 需 HTTP 服务,或手动选择文件 配套地,为了兼顾"双击打开"的场景,加了多候选路径尝试 + 文件选择器 + 拖拽加载 三重兜底: // 多候选路径依次尝试,兼容不同的静态托管方式 var CANDIDATES = ['models/sushi.glb', './models/sushi.glb', '../models/sushi.glb', 'sushi.glb']; function tryFetch(i) { i = i || 0; if (i >= CANDIDATES.length) { loaderEl.classList.add('hide'); showErr('未能自动加载模型。

请选择 sushi.glb,或把 glb 拖拽到页面中。'); return; } loaderEl.classList.remove('hide'); fetch(CANDIDATES[i]) .then(function (r) { if (!r.ok) throw new Error('HTTP ' + r.status); return r.arrayBuffer(); }) .then(loadModel) .catch(function (err) { console.warn('fetch 失败:' + CANDIDATES[i], err); tryFetch(i + 1); // 换下一个候选路径 }); } // 兜底一:文件选择器 fileInput.addEventListener('change', function () { readFile(this.files && this.files[0]); }); // 兜底二:拖拽 glb 到页面 addEventListener('dragover', function (e) { e.preventDefault(); }); addEventListener('drop', function (e) { e.preventDefault(); var f = e.dataTransfer && e.dataTransfer.files && e.dataTransfer.files[0]; if (f) readFile(f); }); function readFile(f) { if (!f) return; var fr = new FileReader(); fr.onload = function () { loadModel(fr.result); }; fr.onerror = function () { showErr('读取文件失败,请重试。'); }; fr.readAsArrayBuffer(f); } #### 3.5 附赠一个坑:本地服务返回 502 改造完成后,用 python -m http.server 8088 起服务,curl 却始终返回 502 ,而端口确实在监听。 排查发现是环境代理 在作祟: env | grep -i proxy # http_proxy=http://127.0.0.1:63845 # https_proxy=http://127.0.0.1:63845 代理把 localhost 请求也拦了。绕过即可: curl --noproxy '' http://127.0.0.1:8088/dingfengbo.html # dingfengbo HTTP=200 BYTES=751108 如果你在容器/公司网络里遇到本地服务莫名 502,先查代理环境变量 ,能省下大量时间。 * * * ### 四、词文呈现:竖排排版与响应式布局 #### 4.1 一行 CSS 达成古籍竖排 古典诗词用竖排才有味道。

CSS 的 writing-mode 让这件事变得异常简单: #poemLines { writing-mode: vertical-rl; / 从右向左竖排 / text-orientation: mixed; / CJK upright,拉丁字母旋转 / max-height: 58vh; } .line { display: block; margin: 0 6px; / 竖排下,块级方向是水平的,左右 margin 即行间距 / font-size: 22px; line-height: 1.9; letter-spacing: .16em; color: #33403a; cursor: pointer; transition: color .25s, background .25s; } .line:hover { color: #3a6b6b; } .line.active { color: #a8322a; background: rgba(168, 50, 42, .10); } 重点吃透 :在 vertical-rl 下,块级元素的排列方向变成了从右到左 ,所以分隔相邻"行"(视觉上的列)要用左右 margin ,而不是上下 margin。这一点非常反直觉,写错了间距会完全不对。 #### 4.2 视觉风格:浅色水墨 配色上走"宣纸 + 青瓷 + 朱印"的路线,克制且耐看: 元素| 色值| 用途 ---|---|--- 宣纸底| #f5f2ec| 页面与场景背景 青瓷| #3a6b6b| 主色调、按钮、强调 墨色| #33403a| 正文词文 朱砂| #a8322a| 朗读高亮、印章 背景再铺一层超大号的装饰文字(低透明度),增加层次但不抢戏: #deco span { position: absolute; font-weight: 700; white-space: nowrap; letter-spacing: .12em; } #deco .d1 { top: 4%; left: -3%; font-size: 20vh; color: rgba(58,107,107,.05); } #deco .d2 { bottom: 2%; right: -4%; font-size: 15vh; color: rgba(58,107,107,.045); } 对应的 HTML 结构:

一蓑烟雨任平生 也无风雨也无晴
#### 4.3 响应式:竖排在小屏上必须让位 竖排在手机上会挤成一团,因此窄屏下切换回横排并移到底部 : @media (max-width: 980px) { #poemCard { right: 12px; left: 12px; top: auto; bottom: 96px; transform: none; } #poemLines { writing-mode: horizontal-tb; max-height: none; } .line { font-size: 15px; margin: 3px 0; letter-spacing: .08em; } #seal, #view3d { display: none; } / 小屏隐藏装饰与三维按钮 / #bar { bottom: 12px; gap: 9px; border-radius: 16px; } }

在这里插入图片描述

      • 五、让东坡先生开口:Web Speech API 逐句朗读与高亮同步 #### 5.1 核心思路:逐句调度而非整段朗读 最直觉的做法是把整首词塞进一个 utterance 一次读完,但这样无法做逐句高亮 ——onboundary 事件在中文上的兼容很不健壮,很多浏览器根本不触发。 可靠的方案是拆句调度 :每一句一个 utterance,靠 onend 驱动下一句,顺便切换高亮。

var synth = window.speechSynthesis; var supported = !!synth && typeof window.SpeechSynthesisUtterance === 'function'; var idx = 0, playing = false, isPaused = false, curUtter = null; function startAt(i) { if (!supported) { alert('当前浏览器不支持 Web Speech 语音合成,建议改用 Chrome / Edge。'); return; } synth.cancel(); // 先清空队列,避免叠加 idx = i; playing = true; isPaused = false; updateBtns(); speakLine(); } function speakLine() { if (!playing) return; if (idx >= POEM.length) { stopAll(); return; } highlight(idx); // 高亮当前句 var u = new SpeechSynthesisUtterance(POEM[idx]); u.lang = 'zh-CN'; u.rate = rate; u.volume = vol; u.pitch = 1.0; var v = currentVoice(); if (v) u.voice = v; curUtter = u; // 关键:持有引用,防止被 GC 中断 u.onend = function () { if (!playing) return; idx++; speakLine(); // 读下一句 }; u.onerror = function () { if (!playing) return; idx++; speakLine(); // 单句出错不要中断整首 }; synth.speak(u); } 三个必须注意的点: 1. curUtter = u 不能省。utterance 若没有外部引用,Chrome 下可能在朗读过程中被垃圾回收,导致读到一半突然静音 。这是 Web Speech 最经典的坑之一。 2. onerror 里要继续推进。个别句子(如含生僻字)可能触发错误,若在这里中断,整首词就卡住了。 3. startAt 里先 synth.cancel()。否则连续点击会排队叠加,出现"两句话同时念"的重叠。

#### 5.2 中文嗓音筛选 speechSynthesis.getVoices() 返回系统里所有语音包,需要筛出中文的;还这个路径是异步 的——页面刚加载时常常返回空数组,必须监听 voiceschanged: function zhVoices() { var vs = (supported ? synth.getVoices() : []) || []; return vs.filter(function (v) { return /^zh|^cmn|Chinese|中文|普通话/i.test((v.lang || '') + ' ' + (v.name || '')); }); } function currentVoice() { if (!supported) return null; var vs = synth.getVoices() || []; if (voiceURI) { var m = vs.filter(function (v) { return v.voiceURI === voiceURI; })[0]; if (m) return m; } var zh = zhVoices(); // 优先 zh-CN,第二任意一个中文嗓音 return zh.filter(function (v) { return /zh[-]CN|cmn[-]Hans[-_]CN/i.test(v.lang || ''); })[0] || zh[0] || null; } // 异步加载:初始调用一次 + 监听变更 if (supported) { populateVoices(); synth.onvoiceschanged = populateVoices; } Windows 上常见的中文嗓音是 Microsoft Huihui / Yaoyao / Kangkang (zh-CN)。如果想让使用者自由切换,把 zhVoices() 的结果渲染进

显示验证码
没有账号?注册  忘记密码?