threejs-dev-setup

何时使用此技能

用户提到以下内容时，始终使用此技能：

• 创建或配置新的 three.js 项目、Vite/Webpack/Rollup 入口，或浏览器 importmap
• 安装 three 包、使版本与文档保持一致，或配置 TypeScript（适用时使用 @types/three）
• three/addons/...、examples/jsm 导入错误、ESM 与 CJS 互操作问题，或裸模块说明符解析问题

重要：此技能与运行时主题的区别

• threejs-dev-setup = 安装路径、打包工具、模块图，以及从何处导入附加组件。
• threejs-renderers = WebGLRenderer / WebGPURenderer、画布、像素比、渲染循环——在项目加载完成后处理。
• threejs-loaders = GLTFLoader、DRACOLoader、进度回调——在导入解析完成后处理。

触发语包括：

• "vite three.js"、"webpack three"、"import map"、"three/addons"、"cannot find module"、"jsm"
• "新建项目"、"安装 three"、"找不到模块"、"ESM"、"TypeScript three"

如何使用此技能

1. 确认交付模式：SPA 打包工具（Vite/Webpack）、Node 工具，或使用 importmap 的静态 HTML——每种模式都会影响 three/addons/ 的解析方式。
2. 固定 three 版本，确保与用户引用的文档版本兼容；注意附加组件路径遵循已发布的软件包布局。
3. 展示规范导入方式：核心内容从 three 导入；控件、加载器和效果从 three/addons/... 导入（在源码树中对应 examples/jsm）。参见 examples/workflow-scaffold.md。
4. 最小渲染循环：创建渲染器、场景、摄像机和一个网格；使用 requestAnimationFrame——足以验证工具链，无需重复深入介绍 threejs-renderers 的内容。
5. TypeScript：启用适合打包工具的 moduleResolution；使用 three 包中的类型声明；除非用户使用无打包工具的 HTML，否则避免重复使用全局脚本标签模式。
6. 出错时：区分缺少依赖、路径错误和 SSR 上下文（没有 window/document）。
7. 深入学习：脚手架运行后，首先向用户推荐 three.js 手册的第一章。

文档导航（官方）

文档部分	代表性链接
手册（入门）	https://threejs.org/manual/
文档索引	https://threejs.org/docs/
软件包 / 安装说明	https://www.npmjs.com/package/three

范围

• 涵盖范围： npm/安装、打包工具、导入映射、three 的 TypeScript 基础、附加组件导入路径、最小验证代码片段。
• 不涵盖： WebGL 理论、完整的渲染目标或后期处理流程（threejs-renderers、threejs-postprocessing）、物理、超出“构建可运行”范围的部署内容。

常见问题和最佳实践

• 在同一页面混用多个 three 副本会破坏单例；使用打包工具别名进行去重。
• 从 node_modules/.../examples/jsm 深层路径导入附加组件并不可靠；如可用，优先使用软件包导出路径 three/addons/...。
• 提供代码片段默认值时，始终遵循 r152+ 风格的色彩管理文档（输出色彩空间）——详情参见 threejs-renderers/textures。
• SSR 框架需要使用动态导入或仅在客户端渲染的组件来创建 WebGL 上下文。

文档和版本

工具链和导入路径遵循用户安装的 three npm 包版本。手册和文档会随库更新；附加组件路径（three/addons/...）必须与该版本的软件包布局一致——如有疑问，请注明版本号，并引用当前文档中的确切导入语句。

Agent 回复检查清单

在此技能下作答时，优先：

1. 说明打包器或运行时（Vite、Webpack、原生 ESM、importmap）以及目标 three 版本。
2. 链接 https://threejs.org/manual/ 和／或 https://threejs.org/docs/，提供权威的设置参考。
3. 区分 threejs-dev-setup（解析）和 threejs-renderers（运行时 API）故障。
4. 除非用户明确使用 CDN／无打包器 HTML，否则绝不假设存在全局脚本标签。
5. 出现重复单例问题时，建议在 package.json／锁文件中对 three 去重。

参考资料

• https://threejs.org/manual/
• https://threejs.org/docs/
• https://www.npmjs.com/package/three

关键词

English： three.js、vite、webpack、rollup、import map、typescript、npm、three/addons、examples jsm、模块解析、脚手架

中文： three.js 安装、构建、importmap、模块解析、three/addons、脚手架、Vite、Webpack