1. GAMES202 作业0 到底要搭什么环境很多人拿到 GAMES202 的第一个作业时会觉得作业0只是环境搭建随手就跳过去了。结果后面写 shading、写 shadow mapping 的时候页面白屏、控制台一片红、纹理加载失败才发现问题全都埋在作业0里。我前后在 Windows、macOS 和 Linux 三种系统上都完整跑过一遍这套框架也帮别人远程看过不少跑不起来的情况这篇就把作业0的环境搭建过程、每一步背后的理由以及我实际踩到的坑一次性讲清楚。先说明白一件事GAMES202 的作业框架本质上是一个基于 WebGL 的实时渲染网页应用。也就是说它不是那种g main.cpp -o main编译出来就能跑的纯 CPU 程序而是需要浏览器、JavaScript 运行时、静态资源服务器三者配合。作业0 的目标非常朴素——把课程提供的框架跑起来在浏览器里看到那个经典的车模或者场景并且能通过右上角的调试面板调节参数、切换不同的渲染效果。只要能稳定看到画面、拖动滑块有实时反馈作业0 就算完成了。为什么这一步值得单独花时间因为课程作业的代码组织方式是基于模块化的 JS 和 WebGL 状态机。你的每一次修改都要经过改源码 → 浏览器加载 → 重新解析 shader → 渲染这个链条链条上任何一个环节的环境问题都会表现成同一个症状黑屏。而黑屏是最难排查的你分不清是代码逻辑错了、shader 编译失败了还是根本没加载到文件。把环境这层先钉死后面调试的搜索空间会小一大半。1.1 从框架结构看环境依赖拿到课程框架压缩包解压之后通常能看到这样几个关键的目录层级理解它们是理解环境依赖的前提。GAMES202/ ├── index.html # 入口页面定义 canvas 和 UI 容器 ├── main.js # 或者 src/main.js程序主逻辑 ├── src/ │ ├── engine.js # 引擎层管理 WebGL 上下文、渲染循环 │ ├── renderer.js # 渲染器负责 draw call │ ├── loaders/ # 模型、纹理、Shader 加载器 │ └── shaders/ # GLSL 顶点/片元着色器 ├── assets/ # 模型文件、贴图、环境贴图 └── lib/ # gl-matrix、dat.gui 之类的第三方库这里面有一个很容易被忽略的事实浏览器出于安全策略不允许file://协议下的页面通过XMLHttpRequest或fetch读取本地文件。这意味着你双击index.html直接打开页面 HTML 和 JS 能跑但加载assets里的.obj模型、.png贴图时会被拦下来报一个跨域CORS错误。这就是为什么环境搭建的第一要务不是装什么库而是起一个本地 HTTP 服务器让页面通过http://localhost:xxxx访问所有资源请求就都在同源策略允许的范围内了。把这个原理记住了很多为什么我双击打开是黑屏的问题就自动有答案了。它跟你的显卡、跟你的浏览器版本都没关系纯粹是协议问题。1.2 三种可行路线对比与选型理由实际能跑通框架的路子有三条我分别用过各有适用场景先给一张对比表后面再展开讲怎么操作。方案依赖启动方式优点缺点推荐场景Python 静态服务器Python 3python -m http.server零安装、一条命令无热更新、无打包只想先看看框架长啥样Node webpackNode.js、npmnpm installnpm run build支持模块化 import、可打包、可热更新依赖多、首次安装慢正式做作业、长期开发VSCode Live ServerVSCode 插件右键 Open with Live Server图形化、改完自动刷新依赖编辑器、大项目偶发卡顿习惯图形界面的人选型的核心判断标准是框架里到底用的是哪种模块组织方式。如果main.js里全是script标签直接引入、或者用import但没配打包工具那就用方案一或方案三如果框架自带package.json、webpack.config.js、并且在main.js里写的是 ES Module 的import ... from ...那基本必须走方案二因为浏览器原生对裸模块说明符bare module specifier比如import { mat4 } from gl-matrix的支持有限直接跑会报 Failed to resolve module specifier。我个人的建议是先用方案一把画面跑起来确认显卡和浏览器没问题再切到方案二做正式开发。这个顺序的好处是如果方案二装依赖时出了问题你已经有一个已知能跑的对照组能快速判断到底是环境问题还是代码问题。注意不要图省事把框架放在带有中文、空格或特殊符号的路径下比如D:\我的作业\图形学 202\。webpack 和部分加载器在处理这类路径时会出问题报错信息还特别隐晦。统一用纯英文、无空格的目录比如D:/workspace/games202/。2. 动手前的工具准备与版本选择环境搭建最容易翻车的地方不是命令写错而是版本不匹配。同一份package.json在 Node 14 上装得干干净净在 Node 22 上可能直接编译失败。所以这一步我要把版本这件事讲透。2.1 Node.js 与 npm 的版本策略先给结论优先选 Node.js 的 LTS 版本推荐 18.x 或 20.x。不要去追最新的 Current 版本。原因在于前端构建工具链里大量依赖会调用 Node 的原生模块编译node-gyp而 gyp 对 Node 的 ABI 版本很敏感。新版本 Node 一出来很多包的预编译二进制还没跟上npm install就会退化成现场从源码编译然后因为缺少 Python 或 C 编译工具直接失败。安装方式上Windows 直接用官网的.msi安装包一路下一步即可安装时会自动把node和npm加进 PATH。macOS 我更推荐用nvmNode Version Manager而不是下载 pkg理由很实际你以后可能会遇到第二个、第三个需要不同 Node 版本的项目用 nvm 可以一条命令切换不会把系统全局环境搞乱。# macOS / Linux 下用 nvm 安装并切换版本 nvm install 18 nvm use 18 node -v # 应输出 v18.x.x npm -v # 应输出 9.x 或 10.x装完之后一定要验证。我见过有人装是装上了但因为 PATH 里存在旧版本残留node -v输出的是 v10自己还没意识到。第二步是配置 npm 的下载源。默认源在境外国内网络环境下npm install经常卡在sill idealTree buildDeps这一步不动一卡就是十几分钟。换成国内镜像源能把这个时间压缩到几十秒npm config set registry https://registry.npmmirror.com npm config get registry # 确认写入成功这里的镜像源指的是 npm 包的同步副本仓库只是把下载地址换到响应更快的服务器上属于常规的开发效率优化。如果你在公司网络或者学校网络下有时候还需要给 npm 配一个http访问通道具体参数问一下网络管理员就行配置方式是npm config set proxy http://你的网络出口地址:端口 npm config set https-proxy http://你的网络出口地址:端口注意如果之后你换了网络环境比如从学校回到家里记得把这两行清掉否则 npm 会一直尝试连那个不存在的出口报ECONNREFUSED。清除命令是npm config delete proxy和npm config delete https-proxy。2.2 Python 与编辑器的配合Python 在这套流程里只承担一个角色提供一个即开即用的静态文件服务器。Python 3 自带http.server模块不需要装任何第三方包。# 在框架根目录有 index.html 的那一层执行 python -m http.server 8000 # 如果系统里 python 指向的是 Python 2改用 python3 -m http.server 8000执行完之后浏览器打开http://localhost:8000就应该能看到框架页面了。这里有个细节必须在含index.html的那一级目录执行。如果你在上一层目录执行访问http://localhost:8000会看到一个文件列表页面得手动点进子目录才行而且相对路径引用容易出错。编辑器方面VSCode 基本是标配。装三个插件就够用了Live Server替代 Python 服务器带自动刷新、Shader languages supportGLSL 语法高亮写 shader 时非常关键、以及 Prettier格式化可选用。GLSL 高亮这个插件我要单独强调一下因为默认情况下.glsl或者内嵌在字符串里的 shader 代码是纯白的一个括号对不齐你都看不出来而 shader 编译错误恰恰是作业里最高频的问题。2.3 目录结构与入口文件的快速解读在敲命令之前花五分钟把index.html和main.js读一遍收益极高。打开index.html重点确认三件事canvas元素的id是什么通常是glcanvas哪些script标签被引入了以及有没有被注释掉的引入行。很多时候框架会提供多个入口比如main.js是主逻辑你把某个script注释掉了页面虽然能打开但什么都不渲染。打开main.js确认第一行是不是import语句。如果是就说明必须走打包路线如果全是函数定义和window.onload那就是直接脚本引入模式。再看src/engine.js里创建 WebGL 上下文的代码const canvas document.getElementById(glcanvas); const gl canvas.getContext(webgl2) || canvas.getContext(webgl);如果课程用的是 WebGL 2 的特性比如 3D 纹理、多重采样渲染缓冲而你浏览器不支持或者显卡驱动被禁用getContext(webgl2)会返回null后面的代码全部报Cannot read property of null。这个坑我会在第 4 章详细展开。3. 完整搭建过程从零到跑通第一个场景这一章是纯实操我按最快看到画面的顺序写每一步都给出验证方法。只要你跟着做中途每一步都是可验证的不会出现做了一堆不知道对不对的情况。3.1 框架获取与目录初始化把课程框架下载下来后解压到一个纯英文路径下然后先做一次目录清点cd /path/to/GAMES202 ls -la # 关注这几个文件是否存在 # index.html main.js package.json webpack.config.js src/ assets/ lib/如果存在package.json用编辑器打开看一眼scripts字段这是后续所有命令的入口{ scripts: { build: webpack --config webpack.config.js, start: webpack serve --config webpack.config.js, dev: webpack --watch }, dependencies: { gl-matrix: ^3.4.3 }, devDependencies: { webpack: ^5.88.0, webpack-cli: ^5.1.4, webpack-dev-server: ^4.15.1 } }这里要注意dependencies和devDependencies的区别。前者是运行时代码依赖的库比如矩阵运算库 gl-matrix打包后会进最终产物后者是只在构建阶段用的工具比如 webpack 本身。有些老版本框架会把 webpack 系列写成固定版本号而不带^这时候不要手贱去改版本号保持原样装能跑就是最好的。顺便检查一下有没有node-sass、sass-loader这类依赖。如果有node-sass请特别注意它在 Node 16 以上版本几乎必然编译失败因为官方已经停止维护并推荐迁移到纯 JS 实现的sassdart-sass。这是我见过最多的作业0卡点具体处理方式在第 4 章。3.2 方案一Python 静态服务器快速跑通这一步的目标是在 3 分钟内看到画面验证显卡、浏览器、资源文件三件事都没问题。# 确保在含 index.html 的目录下 python -m http.server 8000终端会输出Serving HTTP on 0.0.0.0 port 8000 ...。保持这个终端窗口不要关另开浏览器访问http://localhost:8000正常的话你会看到页面背景变成深灰或黑色中间出现渲染出来的模型页面某个角上浮着一个半透明的参数控制面板dat.gui 风格上面有几个折叠起来的文件夹点开能拖滑块。如果这一步就成功了恭喜说明你的硬件和浏览器完全没问题后面装 Node 环境只是为了让开发体验更好。此时你可以直接在assets和src里改代码改完按CtrlF5强制刷新绕过缓存就能看到效果。如果这一步黑屏先按 F12 打开开发者工具切到 Console 面板看报错。具体排查方法在第 4 章但我可以先给你一个高频答案八成是资源 404。切到 Network 面板刷新页面看有没有红色的 404 请求逐个对照路径。3.3 方案二npm webpack 正式开发环境确认画面能出来之后我们切换到正式的开发环境。第一步安装依赖。这一步是整个流程里最耗时的也可能出最多问题npm install正常情况下会看到进度条滚动最后输出added XXX packages in XXs。如果卡在某个步骤超过 5 分钟不动按CtrlC中断然后加上详细日志重跑npm install --verbose # 或者用国内镜像加速 npm install --registryhttps://registry.npmmirror.com第二步构建产物npm run buildwebpack 会从main.js作为入口开始递归解析所有import把它们打包成一个或几个 bundle 文件输出到dist/目录。成功时会输出类似asset main.js 1.24 MiB [emitted] (name: main) webpack 5.88.0 compiled successfully in 3124 ms看到compiled successfully就说明构建过了。这时候再访问http://localhost:8000注意——如果你之前是方案一在跑现在要确认服务器根目录指向的是dist/还是项目根目录。很多框架的webpack.config.js里配置了output.path指向dist而index.html会被 copy 插件复制到dist下这种情况下你应该在dist目录里起服务器或者用方案三直接指向正确位置。第三步启动开发服务器推荐npm startwebpack-dev-server会在内存里编译并起一个本地服务默认端口一般是 8080 或 9000终端会打印出来。它最大的价值是热更新你改完源码保存浏览器自动刷新不用手动切窗口按 F5。做渲染作业这个体验差异巨大因为你可能要调几十次参数。实操心得webpack-dev-server的输出目录在内存里你在硬盘上找不到它生成的文件。所以不要试图去dist目录里找它编译的结果那是两回事。想对比产物就用npm run build想快速开发就用npm start两个命令分开用。3.4 浏览器端验证与调试面板检查环境跑起来之后做一次完整的验证别急着开始写作业代码。第一确认渲染循环在跑。打开src/engine.js找到requestAnimationFrame那一段在里面临时加一行console.log(performance.now())看控制台是不是每帧都在打印。如果是说明主循环是活的黑屏就纯粹是渲染内容的问题。第二确认 shader 编译成功。在创建 shader program 的地方框架一般会有gl.getProgramInfoLog(program)的调用。把它的返回值打印出来正常情况下是空字符串或者仅有无关紧要的警告。如果有ERROR: 0:XX开头的文本那就是 shader 语法错误错误信息里的行号会告诉你具体位置。第三确认调试面板能响应。拖动面板上的滑块观察渲染结果有没有变化。如果滑块动了但画面不动说明参数没有正确传递到 uniform检查renderer.js里 uniform 绑定的代码。第四确认资源全部加载完成。在 Network 面板看所有请求的状态码图片、模型、HDR 环境贴图都应该是 200。如果有 pending 状态一直不结束可能是加载器回调没写对。4. 踩坑实录常见报错与排查技巧这一章是全文最有价值的部分。下面这些报错都是我在真实环境里一条条遇到过、并且记录下解决过程的。我按报错类型分类你可以对照着找。4.1 资源加载类问题症状一控制台报Access to XMLHttpRequest at file:///... has been blocked by CORS policy这是最经典的。原因就是前面说的你用file://协议打开了页面。解决办法只有一个起 HTTP 服务器。不要试图去改浏览器安全设置来绕过那是给自己挖坑。症状二所有资源 404但文件明明就在那儿这种情况十有八九是路径大小写问题。Windows 的文件系统不区分大小写Assets/car.png和assets/car.png都能打开但如果你把代码部署到 Linux 服务器或者用某些严格的加载器就会 404。养成全小写命名目录的习惯代码里的引用也统一小写。另一个可能是相对路径的基准点搞错了。./assets/car.png是相对于当前 HTML 文件所在目录而/assets/car.png是相对于服务器根目录。这两者在项目根目录起服务器时结果一样但一旦你从子目录访问页面就会完全错位。建议统一用相对路径并且在根目录起服务器。症状三模型或纹理加载出来是纯白/纯黑先说纯黑。这通常不是加载失败而是加载成功但渲染结果不对。可能的原因有三个贴图的 UV 坐标没传对、光照计算里法线向量没归一化、或者纹理采样时mix的系数是 0。用调试面板逐个关掉光照、切到基础颜色输出能快速定位。再说纯白。这个更常见通常是纹理加载完成之前就开始渲染了。异步加载的图片要等onload回调触发才能绑定到纹理。如果你在加载函数外面直接调gl.texImage2D那时候图片对象还是空的。另一种可能是渲染器里开了伽马校正但贴图本身已经是 sRGB 编码导致过曝。症状四贴图加载了但显示错位、拉伸检查gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true)这一行。WebGL 的纹理坐标原点在左下角而图片数据的原点在左上角不加这行翻转贴图就是倒的。这个问题在作业里很隐蔽因为画面不是黑的只是看着有点怪。4.2 构建工具类问题症状一npm install卡在sill idealTree buildDeps不动这是网络问题换国内镜像源即可见 2.1 节。如果换了还不行试试把package-lock.json删掉重装rm -rf node_modules package-lock.json npm cache clean --force npm install --registryhttps://registry.npmmirror.com症状二node-sass编译失败报Node Sass could not find a binding for your current environment这是 Node 版本和 node-sass 版本不匹配。三种处理方式按推荐度排序第一种换 Node 版本到 node-sass 支持的版本比如 Node 14。用 nvm 一条命令搞定最省事缺点是用了老环境。第二种把node-sass换成sassdart-sass同时把sass-loader升到 10 以上。纯 JS 实现不依赖编译基本不会有兼容问题。这是官方推荐的方向。第三种删掉node_modules重新npm rebuild node-sass。成功率最低但偶尔有效。症状三Error: Cannot find module xxx依赖没装全。先确认package.json里有没有这个包没有的话说明框架代码引用了新库但配置没更新。有的话执行npm install xxx --save-dev注意区分--save和--save-dev。运行时代码用到的库用--save构建工具用--save-dev。写反了不会立刻报错但以后别人 clone 你的项目装依赖时可能少装东西。症状四Module not found: Error: Cant resolve gl-matrixwebpack 找不到这个模块。检查node_modules/gl-matrix目录是否存在。如果存在但还报错可能是webpack.config.js里的resolve.modules配置有问题或者路径别名写错了。临时应急可以在import里写完整相对路径比如import { mat4 } from ../lib/gl-matrix.js。4.3 浏览器与显卡相关异常症状一getContext(webgl2)返回 null报Cannot read properties of null先访问chrome://gpuChrome 内核浏览器看一眼 WebGL 状态。如果显示 WebGL: Disabled 或者 Software only说明硬件加速被关了。检查浏览器设置里的使用硬件加速模式是否开启检查显卡驱动是否正常。笔记本双显卡的机器有时候会因为集显驱动太老导致这个问题更新驱动基本能解决。症状二画面渲染一会儿突然黑掉控制台报WebGL: CONTEXT_LOST_WEBGL上下文丢失。这个在渲染压力大、或者系统切换显卡的时候会发生。框架里如果没有监听webglcontextlost事件页面就会直接黑掉。作业场景一般不会触发但如果你的模型面数特别大或者开了很多后处理有可能遇到。加一个监听把状态打出来即可定位canvas.addEventListener(webglcontextlost, (e) { e.preventDefault(); console.warn(WebGL context lost, check GPU load or driver); });症状三帧率极低转个视角一卡一卡的先别急着优化算法。打开开发者工具的 Performance 面板录 5 秒看时间花在哪。如果是drawElements单次调用特别久说明整个场景在一次 draw call 里画了太多三角形这个是正常的作业场景本来就重。如果是 JS 侧的函数占了大头那多半是每帧都在做矩阵的重复计算把不变的部分提到循环外就好。4.4 常见问题速查表把上面这些整理成一张表出问题的时候先扫一遍。报错关键词根因处理方式CORS policy / file://用了文件协议打开起 HTTP 服务器用 localhost 访问404 Not Found路径大小写或相对基准错统一小写确认相对路径基准点Node Sass could not find bindingNode 与 node-sass 版本不匹配换 Node 14 或迁移到 dart-sassnpm install 卡住默认源响应慢配国内镜像源清缓存重装Failed to resolve module specifier浏览器直接跑裸 import走 webpack 打包getContext 返回 null硬件加速关闭或驱动异常检查 chrome://gpu更新显卡驱动CONTEXT_LOST_WEBGL渲染负载过高或切换显卡监听事件降低场景复杂度贴图上下颠倒未翻转 Y 轴设置 UNPACK_FLIP_Y_WEBGL页面改了没反应浏览器缓存CtrlF5 强制刷新画面全白资源未加载完就渲染把渲染启动放进加载回调补充一个排查心法先用 Network 面板确认有没有拿到数据再用 Console 面板确认有没有报错最后用 Sources 面板打断点确认代码走到哪一步。这三步顺序不要乱能省掉大量瞎猜的时间。5. 提高效率的实操心得与后续扩展环境跑通只是起点。下面这几点是我做了几个作业之后总结出来的能明显减少无效操作。5.1 热更新与调试效率技巧热更新一定要用起来。npm start之后改src下的任何 JS 文件保存即生效。但有一个细节改 shader 字符串所在的文件有时候热更新不会重新编译 program因为 shader 的编译发生在初始化阶段不在每帧循环里。解决办法是手动刷新页面。这也是为什么我建议把 shader 单独放在.glsl文件里并用加载器读取至少改起来清晰不容易在 HTML 里漏掉一个引号。第二个技巧是给调试面板加自定义项。dat.gui 支持动态添加比如加一个控制曝光度的滑块gui.add(params, exposure, 0.1, 3.0).name(曝光).onChange(v { renderer.setExposure(v); });这样你调参数不用改代码、不用重新编译实时看效果。做后处理相关的作业时这个能省下大量时间。第三个技巧是善用console.time。渲染作业里经常要对比不同算法的性能直接打印时间比肉眼看帧率靠谱console.time(shadowPass); renderer.renderShadowMap(scene); console.timeEnd(shadowPass);5.2 让作业框架更好用的几个小改造这些改造不影响作业评分但能让你少受罪。第一把资源根路径抽成一个常量。框架里如果到处写./assets/xxx.png你换个目录就得全改。在main.js顶部定义一个const ASSET_ROOT ./assets/所有加载器传路径时拼上去。改一次全局生效。第二加一个全局错误提示浮层。页面黑屏时如果能把最近一次捕获的 error 显示在页面角落你就不用来回切窗口看控制台。二十行代码的事收益很大。第三给渲染循环加一个可关的开关。有时候你想在某一帧停住仔细检查渲染状态。加一个let paused false和一个快捷键切换调试时非常方便。第四统一坐标系单位。作业里经常要混入不同的模型如果单位不一致光照强度、相机距离都得跟着调。提前约定好一个单位比如 1 单位 1 米后面省心。5.3 从作业0到后续作业的衔接准备作业0 搭好的这套环境后面会一直用。我建议在做完之后立刻做两件事。第一件把node_modules和构建产物加进.gitignore只提交源码。这样你的仓库体积小别人 clone 下来执行一次npm install就行。忘记这步的话仓库能膨胀到几百兆后续操作都慢。第二件记录一份属于你自己的环境笔记。把 Node 版本、npm 源地址、跑通时的命令、遇到的报错和解决办法写在一个README.md里。原因是这套环境你会在几个月内反复重建比如换了电脑、重装了系统、或者开了一个新的分支想跑个对照实验。有笔记的话重建时间能从两小时压缩到十分钟。另外提前埋一个伏笔后面的作业会涉及 shader 的复杂运算性能会成为瓶颈。如果你现在的机器跑作业0 的默认场景就已经比较吃力那在后续做阴影、做全局光照的时候会更明显。可以考虑在做完作业0 之后顺便测一下当前环境的基准帧率记录下来作为参考。等以后优化算法的时候这个基线数据就是判断到底有没有优化成功的依据。我个人在实际操作中的体会是环境搭建这件事的价值被严重低估了。它不产出任何作业分数但它决定了你后面是花时间在写渲染算法还是花时间在跟构建工具搏斗。作业0 花两小时认真做完后面几个作业能省下至少十个小时的折腾。所以别嫌麻烦一次做扎实。