适用场景
你手上有一个想快速做出来的 3D 展示页面:产品模型旋转展示、数据可视化球体、活动落地页里的粒子场景。你不想从零啃 Three.js 文档,希望用一句话描述需求让模型把整页代码写出来,再自己微调交互、部署到服务器。这套方案适合个人开发者、做运营页面前端同学和需要快速出 Demo 的团队,全程用云端 API,本地不需要显卡。
需要先说明一点:文中提到的 Hy4 flash 指腾讯混元系列里偏重响应速度的模型档位,具体的模型名称、可用参数、控制台入口与计费单价,以腾讯云官方文档和定价页当前展示为准。本文只讲流程、提示词写法与成本核算方法,不写具体数字。
环境与前置条件
- 操作系统:Linux(Ubuntu/Debian 均可)、macOS 或 Windows + WSL 都行,命令以 Linux 为主。
- Node.js:安装当前 LTS 版本,以 Node 官网当前 LTS 为准;只用它跑本地静态服务器和可选的三方依赖,不需要构建工具也能完成。
- 浏览器:Chrome 或 Edge 近两年的版本,需要支持 WebGL2 以便调试。
- 硬件:纯云端调用,本地 8GB 内存、2GB 空闲磁盘足够;无 GPU 要求。生成的是代码,不是模型文件,所以不吃显存。
- 网络:能访问腾讯云 API 域名;页面里如果引用了 CDN 上的 Three.js,还需要浏览器能访问该 CDN。内网环境要提前把依赖下载到本地。
- 账号:已开通混元相关服务并创建 API Key,具备对应模型的调用权限。
先确认 Node 可用:
```bash
node -v
npm -v
```
能打印出版本号即正常。
分步骤部署
第一步:准备 API 密钥与环境变量
在腾讯云控制台开通服务并创建密钥,拿到 SecretId/SecretKey 或 API Key(不同接入方式的凭证形式不同,以官方文档为准)。不要把密钥写进代码或提交到 Git,统一用环境变量:
```bash
export HUNYUAN_API_KEY="你的密钥"
export HUNYUAN_BASE_URL="官方文档中给出的接口地址"
```
确认变量生效:
```bash
echo ${HUNYUAN_API_KEY:0:6}
```
能打印出密钥前 6 位即成功。长期使用建议写进 ~/.bashrc 或改用密钥管理服务。
第二步:建工作目录,起一个本地静态服务器
```bash
mkdir -p ~/web3d/src && cd ~/web3d
```
把模型返回的 HTML 存到 src/index.html,用本地服务器预览(直接双击 file:// 打开会因为模块加载和跨域限制失败):
```bash
cd ~/web3d/src
python3 -m http.server 8080
```
或者:
```bash
npx serve -l 8080
```
浏览器打开 http://localhost:8080,此时页面还可能是空白,属于正常,代码还没生成。
第三步:写好提示词(决定成败的一步)
让模型一次生成可运行的 3D 页面,提示词要同时约束四件事:场景、交互清单、技术栈、输出格式。空泛的“做一个 3D 网页”只会拿到玩具级代码。可直接照抄下面这个模板改:
```text
你是资深 WebGL 前端工程师。请输出一个单文件 index.html,用 Three.js 实现一个 3D 交互场景。
【场景】
一个深色背景的产品展示台:中央是缓慢自转的几何体组合(立方体 + 环面),
地面有柔和的反射,整体色调偏冷,带轻微雾效。
【交互清单】
1. 鼠标左键拖拽旋转视角,滚轮缩放,带阻尼感;
2. 点击几何体时高亮该物体,并在右下角弹出信息卡片显示它的名称;
3. 移动端单指旋转、双指缩放,手势与桌面端一致;
4. 窗口尺寸变化时画面自适应,不拉伸变形。
【技术约束】
- 只用原生 HTML/CSS/JS + Three.js,不引入任何构建工具;
- Three.js 通过 importmap 引入,版本以官方文档当前稳定版为准;
- 所有纹理用 Canvas 或着色器程序化生成,不依赖外部图片和模型文件;
- 动画用 requestAnimationFrame,并按 delta 时间步长计算,避免不同帧率速度不一致;
- 渲染循环里不要每帧新建对象,避免内存泄漏;
- 移动端把 devicePixelRatio 上限压到 2。
【输出格式】
先用 200 字以内说明实现思路,再给一个完整的 html 代码块。
代码必须完整可运行,不要出现省略号、TODO 或“其余同上”。
```
要点:把“不要省略号、不要 TODO”写进约束里。模型偷懒最典型的方式就是省略中间的初始化代码,导致你复制下来一片红。
第四步:调用接口拿到代码
用 curl 先跑通一次,请求体字段名以官方 API 文档为准,下面只给骨架:
```bash
curl -s "${HUNYUAN_BASE_URL}" \
-H "Authorization: Bearer ${HUNYUAN_API_KEY}" \
-H "Content-Type: application/json" \
-d @request.json \
-o response.json
```
request.json 里放模型名、消息数组(system 放角色设定,user 放上面那段提示词)、stream: false 等参数。返回的 response.json 里通常有 usage 字段记录本次消耗的 token 数,这个字段后面核算成本要用,记得留住。
从返回内容里把代码块抽出来落盘。用一段小脚本处理,比手工复制可靠:
```bash
python3 - <<'PY'
import json, re, pathlib
data = json.load(open("response.json"))
text = data["choices"][0]["message"]["content"] # 字段名以官方文档为准
m = re.search(r"``html\n(.*?)``", text, re.S)
pathlib.Path("src/index.html").write_text(m.group(1) if m else text, encoding="utf-8")
print("written", len(text))
PY
```
打印出字符数即写入成功。
第五步:跑起来看效果,按现象改交互
刷新 http://localhost:8080。常见偏差和对应改法:
- 画面全黑但控制台无报错:多半是相机位置在物体内部或光照太暗。追问模型:“相机初始位置改为 (0, 2, 6),加一盏环境光,亮度 0.6”。
- 拖拽没反应或手感发飘:通常是缺
OrbitControls的enableDamping = true,以及没在渲染循环里调用controls.update()。直接把这两条作为要求补进对话。 - 点击拾取不准:让它用
Raycaster,并明确“以画布左上角为原点计算归一化坐标”,这是坐标换算最容易写错的地方。 - 手机上卡顿:要求“关闭后处理、把像素比上限设为 2、几何体分段数减半”。
迭代技巧:不要让模型重写整份代码再覆盖,先让它“只输出需要修改的函数”,改完自己合并;确认可用后立刻 git commit 存一版,否则多轮修改后很难回退。
第六步:部署上线
产物只有一个 index.html(如果本地化了 Three.js,会多一个 vendor/ 目录),属于纯静态资源,扔到 Nginx 或对象存储静态托管都行。以 Nginx 为例:
```bash
sudo mkdir -p /var/www/scene
sudo rsync -av --delete ~/web3d/src/ /var/www/scene/
sudo chown -R www-data:www-data /var/www/scene
```
站点配置:
```nginx
server {
listen 80;
server_name your-domain.example.com;
root /var/www/scene;
index index.html;
location / {
try_files $uri $uri/ /index.html;
}
location ~* \.(js|css|glb|gltf|hdr|ktx2)$ {
add_header Cache-Control "public, max-age=31536000, immutable";
}
gzip on;
gzip_types text/css application/javascript application/json image/svg+xml;
}
```
检查并重载:
```bash
sudo nginx -t && sudo systemctl reload nginx
```
nginx -t 输出 syntax is ok 和 test is successful 即配置正确。之后每次更新只要重跑一次 rsync 即可,无需重启服务。
验证部署是否成功
1. 首页可访问,状态码 200:
```bash
curl -s -o /dev/null -w "%{http_code}\n" https://your-domain.example.com/
```
预期输出 200。404 说明 root 指向错或文件没同步过去。
2. 返回的确实是页面内容:
```bash
curl -s https://your-domain.example.com/ | head -n 5
```
预期看到 <!DOCTYPE html> 和 <html。
3. 压缩生效:
```bash
curl -s -H "Accept-Encoding: gzip" -I https://your-domain.example.com/ | grep -i content-encoding
```
预期输出包含 content-encoding: gzip。
4. 浏览器实测:打开页面,F12 控制台无红色报错;Network 面板里没有 404;拖拽能旋转、点击有反馈;把窗口拉窄到手机尺寸,画面不拉伸、触摸手势可用。
5. 性能粗查:控制台执行 renderer.info.render.calls(变量名按生成代码实际命名),绘制调用数一般控制在几十到一两百之间,明显偏高就说明该合并几何体了。
常见报错与解决
报错 1:HTTP 401,返回内容含 AuthFailure 或 invalid api key
→ 原因:密钥没导出、复制时带了空格,或环境变量只对当前窗口生效。
→ 解决:
```bash
echo "${HUNYUAN_API_KEY:0:6}" # 确认非空
export HUNYUAN_API_KEY="重新粘贴的密钥"
curl -s ... | head -c 300 # 再试一次,看返回体
```
报错 2:HTTP 429,返回内容含 RequestLimitExceeded 或 rate limit
→ 原因:短时间内请求过多,触发接口限流。
→ 解决:改串行调用并加重试退避。
```bash
for i in 1 2 3; do
curl -s "${HUNYUAN_BASE_URL}" -H "Authorization: Bearer ${HUNYUAN_API_KEY}" \
-H "Content-Type: application/json" -d @request.json -o response.json && break
sleep $((i*5))
done
```
报错 3:浏览器控制台 Failed to resolve module specifier "three"
→ 原因:importmap 没写、写错,或映射的 CDN 地址不可达(内网环境常见)。
→ 解决:把 Three.js 下载到本地 vendor/,再把映射指向相对路径。
```bash
npm i three
mkdir -p src/vendor
cp node_modules/three/build/three.module.js src/vendor/
```
页面里改为 "three": "./vendor/three.module.js"。
报错 4:Uncaught TypeError: Cannot read properties of undefined (reading 'appendChild')
→ 原因:脚本执行时挂载容器还不存在,容器 id 拼写不一致,或脚本放在了 <head> 里。
→ 解决:把 <script type="module"> 挪到 </body> 之前,或包一层 DOMContentLoaded,并核对 document.getElementById('app') 里的 id 与 HTML 一致。
报错 5:手机端页面卡死,控制台 THREE.WebGLRenderer: Context Lost
→ 原因:显存/纹理压力过大,像素比过高或后处理过重。
→ 解决:在初始化后加上 renderer.setPixelRatio(Math.min(devicePixelRatio, 2)),去掉 EffectComposer 相关代码,几何体分段数减半。
报错 6:首页能开,刷新二级路径 404
→ 原因:Nginx 缺少 history 模式回退,或缓存文件未同步。
→ 解决:确认 location / 里写了 try_files $uri $uri/ /index.html;,重跑 nginx -t 后 systemctl reload nginx。
后续维护
备份:代码目录纳入 Git,每次生成出可用版本就打标签(git tag v1-可用)。同时保留当次的提示词和返回 JSON,模型版本升级后可以拿旧提示词重跑做对比,避免“新模型效果倒退但找不回旧产物”。Nginx 侧建议用对象存储做一层历史版本归档。
升级:分两类看。前端依赖升级(如 Three.js 大版本)时先看官方迁移说明,重点回归相机、光照、控制器这几块,再上线。模型侧升级时,把旧提示词分别喂给新旧版本,对比生成的代码行数、是否完整、交互是否齐全,用同一套验收清单判定,不要凭感觉。
日志与监控:Nginx 的 access.log 关注 404 和带宽两项,出现大量 404 往往是资源路径大小写或缓存失效导致的。前端加一段 window.onerror 上报,把报错堆栈打到你的收集端,移动端 WebGL 上下文丢失这类问题只有靠上报才看得到。
成本记录:每次调用把返回里的 usage 字段追加进 CSV,字段至少包含日期、用途、输入 token、输出 token。核算方式是:
```text
单次成本 = 输入 token / 1000 × 输入单价 + 输出 token / 1000 × 输出单价
```
两个单价从官方定价页取,注意部分档位有阶梯价、缓存命中折扣或批量优惠,以页面说明为准。做一次 3D 页面的典型流程是“首轮生成 + 3 到 5 轮局部调整”,首轮输出代码通常几千 token,后续每轮输入会带上上一版代码,所以输入 token 会逐轮变大。把这张记录表和实际账单对一遍,你就能判断自己的用量是否落在预算内。如果只是想验证“两毛钱能不能做出一个页面”,可以先只跑首轮生成,记下 usage 再决定要不要继续迭代——多数人的浪费不在单价,而在反复要求模型重写整份代码。
安全提醒:密钥不要出现在前端代码里(无论是否压缩),生成页面的所有调用都应该发生在本地或自建后端;上线前用 grep -r "AKID\|api_key" src/ 扫一遍,别把凭证带上生产环境。
