Motion Canvas Vite 插件全解析motion-canvas/vite-plugin 的架构、配置与演进史【免费下载链接】motion-canvasVisualize Your Ideas With Code项目地址: https://gitcode.com/gh_mirrors/mo/motion-canvasMotion Canvas 是用代码可视化你的想法的动画制作框架而motion-canvas/vite-plugin正是驱动其开发服务器与导出流程的核心基础设施。本文以该包的 CHANGELOG.md 为主干结合仓库源码packages/vite-plugin/src 目录逐层拆解其组合式插件架构、全部配置项、插件扩展机制与 CORS 代理等关键能力并梳理从 2.0.0 到 3.17.2 的版本演进与破坏性变更。读完你将掌握该插件的配置方式、插件扩展点以及历史上迁移到 Vite 架构时发生的核心变化。插件定位Motion Canvas 项目的 Vite 构建层motion-canvas/vite-plugin是一个面向 Motion Canvas 项目的 Vite 插件。其 package.json 声明了vite: 4.x || 5.x的 peer 依赖当前版本 3.17.2并依赖fast-glob项目文件 glob 展开、follow-redirects代理重定向跟随、mime-types导出文件的 MIME 类型映射与source-mapGLSL 源码映射生成。从 2.0.0 起Motion Canvas 正式切换到 Vite 构建体系CHANGELOG 明确记录了当时的安装与配置方式npm i -D vite motion-canvas/vite-plugin在项目根目录创建vite.config.tsimport {defineConfig} from vite; import motionCanvas from motion-canvas/vite-plugin; export default defineConfig({ plugins: [motionCanvas()], });对应到仓库packages/vite-plugin/src/index.ts只是简单地将main.ts作为默认导出并转发插件类型真正的插件组装逻辑位于 packages/vite-plugin/src/main.ts。组合式架构一个入口九个功能子插件main.ts中的默认导出函数接收MotionCanvasPluginConfig配置返回一个 VitePlugin[]数组即一个入口同时向 Vite 注册多个内部插件。这种组合式设计让每个关注点场景加载、元数据、导出、代理等都拥有独立的 Vite 插件实现便于维护与按需启用子插件名称职责源码metaPlugin()motion-canvas:meta编译.meta文件、处理编辑器对元数据的写回WebSocketpartials/meta.tssettingsPlugin()motion-canvas:settings提供virtual:settings.meta虚拟模块持久化应用设置partials/settings.tsscenesPlugin()motion-canvas:scene拦截?scene查询参数为场景文件生成包装模块并接入 HMRpartials/scenes.tsexporterPlugin()motion-canvas:exporter通过 WebSocket 接收帧数据写入输出目录提供打开输出目录接口partials/exporter.tseditorPlugin()motion-canvas:editor解析编辑器包默认motion-canvas/ui的 HTML/样式/入口partials/editor.tsprojectsPlugin()motion-canvas:project处理?project查询、生成项目引导模块、覆盖 Vite 构建配置partials/projects.tsassetsPlugin()motion-canvas:assets资源缓冲buffered assets与音频 HMR 延迟处理partials/assets.tswebglPlugin()motion-canvas:webgl解析 GLSL 的#include、拼接着色器并生成 source mappartials/webgl.tscorsProxyPlugin()motion-canvas:cors-proxy为远程资源提供/cors-proxy/...代理默认关闭partials/corsProxy.tsprojectsPlugin是其中最核心的一个它通过configResolved阶段收集所有带PLUGIN_OPTIONS符号的插件见 plugins.ts并在config(config)钩子中为整个 Vite 配置注入 Motion Canvas 所需的默认项——JSX 自动运行时jsxImportSource: motion-canvas/2d/lib、默认 dev server 端口9000、构建输入每个项目文件带?project查询、以及optimizeDeps.exclude: [preact, preact/*, preact/signals]。CHANGELOG 中 exclude preact from optimizations3.12.0、remove dependency pre-bundling warning3.8.0与 fix dependency bundling3.12.1/3.12.2等修复均落在这个钩子附近。核心配置项详解MotionCanvasPluginConfig的完整定义在 packages/vite-plugin/src/main.ts#L18-L96其中包含的默认值如下motionCanvas({ project: ./src/project.ts, // 项目文件或文件数组支持 glob output: ./output, // 渲染输出目录 bufferedAssets: /^$/, // 需要缓冲的资源正则默认不缓冲 editor: motion-canvas/ui, // 编辑器包导入路径 proxy: undefined, // CORS 代理配置默认关闭 buildForEditor: undefined, // 是否以编辑器模式构建 })project多项目与 glob 支持project接受单个字符串或字符串数组并通过 utils.ts 中的getProjects展开若路径是动态模式fg.isDynamicPattern则用fast-glob同步展开为真实文件列表。CHANGELOG 3.12.0 的 support glob for project files 正是这一能力而更早的 support for multiple projects2.0.0则让数组形式成为可能。每个项目对应的.meta文件若不存在会在createMeta中被自动创建为{version: 0}项目显示名优先取自 meta 文件中的name字段——对应 3.4.0 的 get name from meta file。output输出目录与分组导出output默认./output在main.ts中被path.resolve转为绝对路径后传给exporterPlugin。导出器通过 WebSocket 消息motion-canvas:export接收{data, frame, name, subDirectories, mimeType}用mime-types根据 MIME 类型推导扩展名再写入output/subDirectories/name.extpartials/exporter.ts。subDirectories支持按场景分组输出对应 CHANGELOG 3.3.0 的 add option to group output by scenes3.12.0 的 create empty output directory if not exist 与 handle unusual characters in file names关闭 #764也在此实现3.15.1 的 optimize saving frames to disk 优化了逐帧写入而 3.7.0 的 button for opening the output directory 则通过/__open-output-path中间件不存在时先建目录调用openInExplorer打开系统文件管理器。bufferedAssets资源缓冲bufferedAssets接受一个RegExp或false用于解决大资源流式读取导致其他应用无法覆写文件的问题例如音频文件被 Adobe Audition 视为占用。启用后assetsPlugin 会在 dev server 中间件中匹配到该正则的资源时先readFileSync全量读入内存再从内存流式输出从而让磁盘上的原始文件保持可写HMR 依然可用。默认值/^$/匹配不到任何路径即默认不缓冲。editor编辑器包路径editor指定编辑器包的导入路径按 Node 模块解析规则解析默认motion-canvas/ui。该包需包含editor.htmlHTML 模板、styles.css样式以及导出editor接收项目工厂创建 UI与index接收项目列表创建项目选择页两个工厂函数的main.js。多项目支持2.0.0与项目选择界面3.14.1 修复的 fix project selection screen、3.17.2 修复的 project file path on selection都依赖此机制。proxyCORS 代理2.6.0 引入CHANGELOG 2.6.0 的 add CORS Proxy 解决了远程资源跨域问题在预览模式下直接访问远程资源可以工作但导出读取 canvas时会因 CORS 失败。代理将所有远程资源经由同源的/cors-proxy/...提供从而绕过限制。其配置类型定义在 partials/corsProxy.ts#L8-L29motionCanvas({ proxy: { allowedMimeTypes: [image/*, video/*], // 允许的资源类型支持左侧通配 allowListHosts: [example.com], // 主机白名单默认空数组 允许任意主机 }, })也可以直接传true启用默认配置。实现细节包括仅接受 GET 请求其他返回 405、协议仅限 http/https、通过allowedMimeTypes校验响应Content-Type格式必须是左/右左侧可为*传空数组表示全部允许、通过allowListHosts精确匹配主机名、使用follow-redirects跟随重定向并复制原响应头、额外写入x-proxy-destination头后直接pipe流式转发。代理启用状态还会通过VITE_MC_PROXY_ENABLED、VITE_MC_PROXY_ALLOW_LIST环境变量暴露给前端。buildForEditor编辑器构建模式buildForEditor打开后projectsPlugin会将构建目标设为esnext、项目引导模块改用editorBootstrap用于构建出可在编辑器内运行的项目。插件扩展机制让插件覆盖配置、注入运行时入口CHANGELOG 3.4.0 的 plugin architecture 与 3.8.0 的 add new hooks for plugins 共同奠定了可扩展性插件本身就是带PLUGIN_OPTIONS符号Symbol.for(motion-canvas/vite-plugin/PLUGIN_OPTIONS)的普通 Vite 插件。PluginOptionsplugins.ts#L43-L98提供三个能力entryPoint运行时插件入口模块说明符。项目引导模块会为每个带入口点的插件生成import pluginN from entryPoint并调用pluginN(options)见 partials/projects.ts#L44-L56使自定义代码进入浏览器端。config(config)配置钩子。在 Vite 的configResolved阶段main.ts会收集全部插件并对config依次调用该钩子返回值与当前配置浅合并——这正是 3.17.0 let plugins override config关闭 #1054的实现方式后注册插件的返回值会覆盖先前的projects或output。runtimeConfig()运行时配置钩子。返回对象时经 JSON 序列化注入返回字符串时原样注入代码从而支持正则、函数等不可序列化值。另外3.3.0 的 cant assign port 修复、3.12.0 对 preact 的optimizeDeps排除都体现在projectsPlugin的config返回结构partials/projects.ts#L78-L104中。meta 文件与场景加载?scene/?project查询参数机制CHANGELOG 2.0.0 的破坏性变更引入了?scene查询参数约定——场景文件不再需要遵循[name].scene.tsx命名而是在项目文件中显式声明import example from ./scenes/example?scene; export default new Project({ name: project, scenes: [example], });其底层实现是scenesPlugin的正则匹配/[?]scene\b/命中后生成一个包装模块自动创建同名.meta文件将场景描述符description与 meta 文件关联并挂接import.meta.hot实现场景级热更新partials/scenes.ts。与之对称projectsPlugin通过/[?]project\b/拦截项目文件生成调用bootstrap或editorBootstrap的引导模块并把各插件的运行时入口与virtual:settings.meta一并注入。meta 文件的编辑器写回由metaPlugin处理编辑器通过 WebSocketmotion-canvas:meta消息提交新内容插件将其写入磁盘并通过 1 秒时间戳窗口在handleHotUpdate中抑制自触发刷新避免编辑器保存 → 文件变更 → 编辑器重载的循环partials/meta.ts。应用设置则持久化在用户主目录的~/.motion-canvas/settings.json对应 3.9.0 的 application settings。WebGL 着色器与音频 HMRWebGL shaders3.14.0webglPlugin会拦截.glsl文件解析#include ...指令递归拼接着色器源码检测循环包含并抛错通过addWatchFile让被包含文件参与监听最后用source-map生成带includeMap的源码映射以便调试时定位到真实文件partials/webgl.ts。仓库自带的着色器示例见 packages/core/shaders/common.glsl 与 packages/core/shaders/fragment.glsl。音频 HMR3.11.0assetsPlugin的handleHotUpdate会识别.mp3|wav|ogg|aac|flac资源并在热更新前延迟 1 秒确保播放器先释放旧资源partials/assets.ts#L36-L56这就是 CHANGELOG 2.0.0 improve audio handling 与 3.11.0 hot module replacement for audio 的延续。版本演进时间线从 Vite 迁移到 3.17.2以 CHANGELOG 为线索可以还原该包的能力演进轨迹2.0.02023-02-04移除旧包并全面切换到 Vite新增多项目、多播放器、场景独立命名、并发导出、CORS 能力基础见下、markdown 日志、导航到场景与节点源码等同时引入?scene查询与Project类导出详见下一节迁移说明。2.1.02023-02-07修复 HTML 响应缺少头部的问题。2.4.02023-02-18修复 dev server 中忽略查询参数。2.6.02023-02-24新增 CORS Proxy。3.0.02023-02-27新播放架构makeProject不再接受background、audioOffset等设置这些设置移入项目 meta 文件。3.1.0 ~ 3.2.02023-03仅版本号提升界面显示当前包版本。3.3.02023-03-18修复端口无法指定新增按场景分组输出Vite 从 v3 升级到 v4。3.4.02023-03-28项目名取自 meta 文件引入插件架构。3.7.02023-05-10新增打开输出目录按钮定稿自定义导出器。3.8.02023-05-13移除依赖预打包警告为插件新增 hooks。3.9.02023-05-29应用设置新增插件入口点entryPoint。3.10.0 ~ 3.13.02023-07 ~ 2024-01多数为版本号提升Version bump only。3.12.x2023-12-31glob 项目文件、输出目录自动创建、文件名特殊字符、preact 排除、依赖打包修复。3.14.02024-02-04WebGL 着色器支持。3.14.12024-02-06修复项目选择界面。3.15.12024-03-21优化帧写入磁盘性能。3.17.02024-08-13允许插件覆盖配置。3.17.22024-12-14修复项目选择时项目文件路径问题。迁移要点2.0.0 与 3.0.0 的破坏性变更CHANGELOG 在 2.0.0 条目下用三个 BREAKING CHANGES 记录了当时最重要的迁移动作这也是理解插件职责的关键1. 导入路径变更。移除旧包、统一新的导入路径场景导入必须使用?scene查询参数示例见上文。2. 项目结构变更。Vite 与motion-canvas/vite-plugin成为构建必需项根目录新增vite.config.ts。同时Motion Canvas 的类型不再全局暴露需要在src目录创建motion-canvas.d.ts/// reference typesmotion-canvas/core/project /3.bootstrap函数移除。项目文件不再调用bootstrap()而是默认导出Project类的实例import {Project} from motion-canvas/core/lib; import example from ./scenes/example.scene; export default new Project({ name: project, scenes: [example], // 原 bootstrap() 中的可用选项继续支持 });随后的 3.0.0 又进一步收紧了makeProjectbackground、audioOffset等展示类设置被移入项目 meta 文件由metaPlugin统一管理并持久化。当前仓库中的template与examples等包如 packages/template/vite.config.ts、packages/template/src/motion-canvas.d.ts、packages/template/src/project.ts即遵循这一新结构可作为现成的参考实现。小结motion-canvas/vite-plugin通过一个入口函数组合九个功能子插件的架构把场景加载、meta 持久化、帧导出、CORS 代理、GLSL 编译、音频 HMR 等能力清晰地组织在 Vite 插件生态内。其演进历史CHANGELOG.md完整呈现了从 2.0.0 的 Vite 迁移、多项目与插件架构的建立到 3.17.0 配置可被插件覆盖的成熟过程。对于要在自己的 Motion Canvas 项目中配置构建、扩展编辑器或接入远程资源的工作流这份 CHANGELOG 与 packages/vite-plugin/src 下的源码是目前最直接、最权威的参考。【免费下载链接】motion-canvasVisualize Your Ideas With Code项目地址: https://gitcode.com/gh_mirrors/mo/motion-canvas创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考