glass-easel：微信小程序 Skyline 底层组件框架接入与使用指南

一、项目官方信息

glass-easel 是微信小程序官方的新版组件框架核心实现，也就是 Skyline 渲染引擎背后的组件化 UI 框架。它在 README 中的定位是：一个 JavaScript 的组件化界面框架，用来进行组件化、定义式的界面开发。

它是对旧版小程序组件框架的完全重写：保持对旧版特性的兼容（99% 接口兼容），同时加入新特性。最关键的一点是——它的运行时并不依赖小程序环境，可以独立运行在 Web 或其他 JavaScript 环境下，从而让同一份组件代码在 Web 和小程序之间共享。

二、官方图片

上图为 glass-easel 官方仓库 Logo（logo_256.png）。该项目以 TypeScript 编写并提供 TSDoc 接口文档，本身不包含 <view /> <image /> 等内置组件实现，只提供组件框架本身。

三、环境要求

• 已安装 Node.js 16 及以上版本与 npm。
• 若要在小程序中使用 Skyline 渲染，需使用微信开发者工具最新版本，并在项目配置里开启 Skyline 渲染。
• 若要自行编译两个编译器子模块（template-compiler、stylesheet-compiler），需额外安装 Rust 与 wasm-pack——日常使用直接装 npm 预编译包即可，无需自行编译。
• 推荐 TypeScript 项目，以获得更好的类型提示。

四、接入步骤

1. 初始化 npm 环境

在小程序项目根目录执行：

npm init -y

微信开发者工具需在「详情 → 本地设置」中勾选「使用 npm 模块」，并通过菜单「工具 → 构建 npm」生成 miniprogram_npm 目录。

2. 安装所需子模块

官方 README 原文：与普通 npm 包类似，安装你需要用到的子模块即可。

npm install --save glass-easel
npm install --save-dev glass-easel-template-compiler

各子模块的职责（README 子模块表）：

3. 选择接入方式

• 只做小程序内部开发：直接用小程序原生自定义组件写法即可，无需手动安装 glass-easel——它是小程序运行时的一部分。
• 要在 Web 与小程序之间共享代码：联合使用 glass-easel 核心 + glass-easel-miniprogram-adapter + glass-easel-miniprogram-webpack-plugin，即可用 WXML / WXSS / JS 三类文件组织代码，让项目结构与小程序相仿，同时能跑在 Web 上。

4. 使用官方项目模板起步

README 提供了一个参考项目模板 glass-easel-miniprogram-template。直接克隆后安装依赖即可在其上二次开发：

git clone https://github.com/wechat-miniprogram/glass-easel.git
# 进入 glass-easel-miniprogram-template 子目录后安装依赖

5. 验证

• 在微信开发者工具中打开项目，构建 npm 后，控制台无报错。
• 按 TSDoc 文档（见文末跳转）编写一个最简自定义组件，能正常渲染。

五、使用方法

• 后端（Backend）概念：这是 glass-easel 的核心思想。后端表示组件系统的运行环境——在 Web 下是浏览器 DOM 接口，在小程序下是小程序环境接口。后端无关的组件代码因此可以跨环境复用。
• 组件模板 / 事件 / 生命周期：glass-easel 完整实现了小程序自定义组件的全部特性，包括模板、通信与事件、生命周期等，接口与小程序自定义组件一致。
• 单组件树更新算法：它沿用旧版的单组件节点树更新算法，性能均衡，适合高度组件化开发。
• TypeScript 支持：核心模块支持 TSDoc，自动生成的接口文档在 GitHub Pages（见跳转链接）。
• 配套开发工具：官方提供 glass-easel-analyzer（VSCode 扩展）、glass-easel-devtools（开发者工具插件）、glass-easel-i18n（国际化），按需安装。

六、常见问题 FAQ

1. glass-easel 是小程序 SDK 的一部分吗？ 按 README 区分：glass-easel 是小程序运行时的一部分；两个 compiler 是小程序编译器的一部分；而 miniprogram-adapter 与 miniprogram-webpack-plugin 不是，它们是为了在 Web 环境模仿小程序接口而设计的。

2. 安装后为什么没有 <view /> <image /> 这些组件？ glass-easel 只是组件框架本身，不包含内置组件实现。README 说明这些组件实现非常复杂、与微信环境接口耦合很深，不能直接复用到 Web；未来会考虑提供常用组件的等价 Web 实现。

3. 直接 import 'glass-easel' 在小程序里就能用吗？ 目前小程序代码还不能直接调用 glass-easel 子模块，因为官方仍在确认接口稳定性与兼容性。稳定后，小程序才能选择用 glass-easel 作为组件框架实现。日常小程序开发用原生自定义组件写法即可。

4. 想在 Web 与小程序共享代码该怎么做？ 联合使用核心模块 + miniprogram-adapter + miniprogram-webpack-plugin，用 WXML/WXSS/JS 组织代码。注意：自定义后端、自定义模板引擎、外部组件等高级特性受小程序环境与安全策略限制，共享代码时请以小程序自定义组件接口为准，避免用到这些受限特性。

5. 和旧版组件框架有什么差异？ glass-easel 包含旧版全部特性、99% 接口兼容，但它是完全重写，仍有细微的接口表现差异，官方在正式开放前会继续打磨兼容性，并加入若干新特性。

6. 两个 compiler 一定要自己编译吗？ 不需要。它们虽用 Rust 编写，但发布时已提供 npm 预编译包。只有你要修改编译器源码时，才需要安装 Rust 与 wasm-pack。

七、跳转链接

• GitHub 仓库：https://github.com/wechat-miniprogram/glass-easel
• 核心模块 TSDoc 文档：https://wechat-miniprogram.github.io/glass-easel/docs/glass-easel
• 适配器 TSDoc 文档：https://wechat-miniprogram.github.io/glass-easel/docs/glass-easel-miniprogram-adapter
• npm 包：https://www.npmjs.com/package/glass-easel
• Road Map：https://github.com/wechat-miniprogram/glass-easel/milestones