直接双击打开 html 文件会报错，因浏览器禁止 file:// 协议下加载 es 模块，import * as three from 'three' 无法解析；必须使用 live server 或 vite 等开发服务器运行项目。
为什么直接双击打开 HTML 文件会报错 Failed to resolve module specifier "three"
浏览器禁止 file:// 协议下加载 ES 模块，而 import * as THREE from 'three' 是标准模块语法。不启动本地服务器，连最基本的 import 都会失败，更别说后续的纹理、GLTF 模型加载。
必须用开发服务器，不能靠右键“在浏览器中打开”。可行方案只有两个：
-
Live Server扩展：右键index.html→ “Open with Live Server”，适合单页快速验证，端口固定为5500，无构建步骤 -
vite：运行npm create vite@latest选vanilla或javascript，再npm install three @types/three，启动npm run dev（默认localhost:5173）。它支持热更新、按需加载、import路径自动解析，是 Three.js 中大型项目的事实标准
别用 parcel 或原生 http-server：前者对 three/addons/ 路径处理不稳定；后者完全不支持模块导入。
如何让 THREE. 输入后弹出完整属性和方法提示
光装 three 包不够，VSCode 默认不认识它的类型定义。必须显式引入类型支持：
- 执行
npm install --save-dev @types/three（注意是--save-dev，不是--save） - 确保项目根目录有
jsconfig.json（JavaScript 项目）或tsconfig.json（TypeScript 项目），哪怕内容为空（{}）——这是 VSCode 启用类型检查的开关 - 如果用了
vite，确认vite.config.js中没有禁用resolve.alias，否则import { OrbitControls } from 'three/addons/controls/OrbitControls.js'可能无法被正确索引
重启 VSCode 窗口（不是重载窗口），打开 .js 文件输入 THREE.，就能看到 Scene、Mesh、Vector3 等完整补全列表。没提示？先检查终端里 node_modules/@types/three 是否真实存在。
怎么给 .frag / .vert 文件加 GLSL 语法高亮
VSCode 默认把 .frag 当纯文本，着色器写在模板字符串里也不会识别。两步解决：
- 安装扩展
GLSL（作者cadenas，IDcadenas.vscode-glsllint）——别装带linter或validator的变体，它们会误报#include <common></common>为错误 - 手动绑定后缀：打开任意一个
shader.frag文件 → 点右下角语言模式（显示 “Plain Text”）→ “Configure File Association for '.frag'” → 输入glsl回车；对.vert和.glsl重复操作
内联着色器字符串要加注释触发：// language=glsl 必须紧贴反引号前，且不能有空格，例如：
const vertexShader = `// language=glsl
varying vec2 vUv;
void main() {
vUv = uv;
gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
}`;
写成 /* @lang glsl */ 或换行都会失效。
为什么 OrbitControls 或 GLTFLoader 提示 “Cannot find module”
Three.js 自 v152 起把所有插件移出主包，统一放在 three/addons/ 下，路径必须写全，且后缀 .js 不可省略：
- ✅ 正确：
import { OrbitControls } from 'three/addons/controls/OrbitControls.js' - ❌ 错误：
import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls'（旧路径已废弃） - ❌ 错误：
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js'（少写loaders/会导致找不到）
如果仍报错，检查 node_modules/three 目录下是否存在 addons/ 子目录；若不存在，说明 npm install three 没成功，删掉 node_modules 和 package-lock.json 重装。
最易被忽略的一点：Vite 项目中，import 路径里的 three/addons/... 是由 Vite 的模块解析规则自动映射的，但如果你手动改过 vite.config.js 的 resolve.alias 或启用了 optimizeDeps.exclude，就可能破坏这个映射——此时补全和运行都会出问题，得逐项核对配置。
