Skia demos.skia.org 本地运行指南：用本地 CanvasKit 构建调试 Web 2D 演示-平芜编程栈

图形学

【免费下载链接】skia

Skia is a complete 2D graphic library for drawing Text, Geometries, and Images. See documentation for contribution instructions.

项目地址：https://gitcode.com/gh_mirrors/ski/skia

点击查看免费下载

导读

本文围绕 Skia 仓库中demos.skia.org目录的 README.md，完整讲解如何在本机编译 CanvasKit（Skia 的 WebAssembly 版本），并通过本地 Web 服务器运行仓库自带的各类 Web 2D 演示页面。读完本文，你将掌握从"构建 CanvasKit"到"将 demo 从 CDN 切换为本地构建"再到"浏览器验证"的完整调试链路，适合希望深入 CanvasKit 源码、修改 API 行为或开发新 demo 的开发者。

一、demos.skia.org：Skia 的 Web 演示集

demos.skia.org是 Skia 仓库中专门存放 Web 演示页面（demo）的目录，其配套文档只有一份精炼的 README.md，核心思路非常清晰：

先用本地源码构建一份 CanvasKit（WASM 产物）；
在该目录启动一个本地静态 Web 服务器；
修改 demo 页面，让它们从本地服务器加载构建产物，而不是默认的公共 CDN。

从目录结构看，demos.skia.org/demos/下共包含 13 个演示子目录：hello_world、canvas_edit、image_decode_web_worker、image_sampling、mesh2d、path_performance、sampling_types、spreadsheet、textedit、textures、up_scaling、web_worker、webgpu。从目录名可以推断，这些 demo 覆盖了 CanvasKit 的典型能力：基础绘制、图像采样与解码、Web Worker 并行处理、文本编辑、网格（mesh）、纹理、路径性能以及 WebGPU 渲染等，可以作为本地调试和 API 学习的第一手素材。

二、前置条件：编译本地 CanvasKit

README 的第一步要求进入 CanvasKit 源码目录并完成一次构建：

cd modules/canvaskit make debug # 或 make release 等其它目标

modules/canvaskit目录下的 Makefile 提供了丰富的构建目标，几个常用目标如下：

目标	对应编译参数	适用场景
`make debug`	`./compile.sh debug_build`	日常调试，编译更快、错误信息更友好
`make release`	`./compile.sh release`	发布级构建，体积更小、性能更好
`make release_cpu`	`./compile.sh cpu_only`	关闭 GPU 后端，仅保留 CPU 渲染
`make debug_webgpu`	`./compile.sh debug_build use_webgpu`	使用 WebGPU 后端的调试构建
`make profile`	`./compile.sh profiling`	性能剖析专用构建
`make with_debugger`	`./compile.sh debug_build enable_debugger`	为 Skia Debugger 集成调试版

以debug目标为例，它内部依次执行：

调用 compile.sh 以debug_build参数生成 GN 构建配置并编译；
创建build/目录；
把产物canvaskit.js和canvaskit.wasm复制到build/下。

从 compile.sh 源码可以看到，构建本质上是./bin/gn gen+ninja的流程：脚本会根据传入的参数开关决定大量 GN 参数，例如is_debug、skia_enable_ganesh、skia_enable_graphite、skia_use_webgl、skia_use_webgpu、skia_enable_skottie、skia_canvaskit_enable_font等。这也是为什么make debug比make release更快——debug 构建关闭了优化、保留更友好的报错信息（参见 modules/canvaskit/README.md 中 "make debug is much faster and has better error messages" 的说明）。

需要说明的适用前提：按 modules/canvaskit/README.md 的要求，编译 CanvasKit 需要先下载并激活 Emscripten 工具链（仓库通过bin/activate-emsdk完成），并已按 Skia 官方方式同步好依赖；测试相关命令还要求 Node.js v14 及以上。

三、启动本地 Web 服务器：make local

CanvasKit 构建完成后，回到demos.skia.org目录运行：

cd demos.skia.org make local

demos.skia.org/Makefile 中local目标完整做了三件事：

local: echo "Go check out http://localhost:8123/demos/hello_world/index.html" rm -f build ln -s ../modules/canvaskit/build build python3 -m http.server 8123

在demos.skia.org下创建一个名为build的符号链接，指向../modules/canvaskit/build，从而让 web 服务器可以直接以/build/...路径访问到刚刚编译好的 CanvasKit 产物（canvaskit.js与canvaskit.wasm）；
用 Python 自带的http.server在8123端口启动静态文件服务；
终端会提示访问入口http://localhost:8123/demos/hello_world/index.html。

因此运行成功后，在浏览器打开上述地址即可看到 CanvasKit 的 Hello World 演示。该目录下所有 demo 均可通过http://localhost:8123/demos/<demo名>/index.html访问，例如webgpudemo 对应http://localhost:8123/demos/webgpu/index.html。

四、让 demo 从本地加载而非 CDN

README 特别强调：你需要修改 demo，让它从本地 Web 服务器加载构建产物，而不是公共 CDN。这一步是整个调试流程的关键，因为 demo 默认会通过unpkg.com/canvaskit-wasm加载发布到 npm 上的稳定版 CanvasKit，而非你本地刚刚编译的版本。

以 demos.skia.org/demos/hello_world/index.html 为范本，可以看到两种加载方式的切换写法：

<!-- 默认方式：从 CDN 加载（本地调试时注释掉） --> <!-- <script type="text/javascript" src="https://unpkg.com/canvaskit-wasm@0.25.0/bin/full/canvaskit.js"></script> --> <!-- 本地方式：从本地服务器加载 --> <script type="text/javascript" src="/build/canvaskit.js"></script>

对应的 JS 初始化部分同样有两套 base 路径：

// 从 CDN 加载时： // const base = 'https://unpkg.com/canvaskit-wasm@0.25.0/bin/full/'; // 本地调试时： const base = '/build/'; const ckLoaded = CanvasKitInit({ locateFile: (file) => base + file });

CanvasKitInit的locateFile回调用于告诉 WASM 运行时到哪里寻找.wasm文件：当页面脚本来自/build/canvaskit.js时，locateFile把请求的文件（如canvaskit.wasm）拼成/build/canvaskit.wasm，正好命中make local创建的符号链接。这个模式是demos.skia.org下所有 demo 切换本地构建的通用套路：把<script src>与base变量都改为指向/build/即可。

加载成功后，ckLoaded.then((CanvasKit) => ...)回调里即可使用 CanvasKit API 创建画布表面：

const surface = CanvasKit.MakeCanvasSurface('draw'); const paint = new CanvasKit.Paint(); paint.setColor(CanvasKit.RED); const textFont = new CanvasKit.Font(CanvasKit.Typeface.GetDefault(), 20); function drawFrame(canvas) { canvas.drawRect(CanvasKit.LTRBRect(10, 10, 50, 50), paint); canvas.drawText('If you see this, CanvasKit loaded!!', 5, 100, textPaint, textFont); } surface.requestAnimationFrame(drawFrame);

页面中那行 "If you see this, CanvasKit loaded!!" 文本本身就是对"本地构建是否成功加载"的最直观验证：看到它，说明本地 CanvasKit 已在浏览器中正常运行。

五、验证与常见问题

1. 如何确认加载的是本地构建而不是 CDN 版本？

修改modules/canvaskit下的源码后重新执行make debug，再刷新 demo 页面，若行为随之变化，即可确认链路已切换到本地构建；也可以借助浏览器开发者工具的 Network 面板查看canvaskit.js的请求来源是否为localhost:8123。

2. 为什么需要先构建 CanvasKit 再启动make local？

因为make local只是创建指向modules/canvaskit/build/的符号链接并启动服务器，它本身不触发编译。若尚未构建，/build/canvaskit.js将 404，页面会因无法执行CanvasKitInit而报错。顺序必须是：先make debug（产出 build 目录），再make local（启动服务）。

3. 构建版本选 debug 还是 release？

日常修改与调试建议make debug（编译快、错误信息完整）；验证体积、性能或发布行为时再切换到make release等目标，两者的产物都会输出到modules/canvaskit/build/，无需改动 demo 页面的加载方式。

4. 端口与访问入口

服务器固定监听8123端口（见 demos.skia.org/Makefile 中的python3 -m http.server 8123），默认演示入口为http://localhost:8123/demos/hello_world/index.html。

总结

demos.skia.org为 Skia 的 Web 端能力提供了一个开箱即用的本地调试环境：通过 modules/canvaskit/Makefile 的make debug编译出本地 CanvasKit，再经 demos.skia.org/Makefile 的make local在 8123 端口拉起静态服务，最后按 demos.skia.org/demos/hello_world/index.html 的模式把 demo 的脚本与base路径切换到/build/，即可在浏览器中直接体验和调试基于本地源码的 CanvasKit 行为——这也是深入阅读 Skia 源码、二次开发 CanvasKit 功能时最实用的起步流程。