1. 从“artcraft”这个名字说起它到底想解决什么问题第一次看到“artcraft”这个标题我脑子里蹦出来的第一反应是“艺术”加“手艺”一个把创意和动手能力揉在一起的东西。后来跟几个做独立开发的朋友聊发现大家对这个词的理解出奇地一致它不是一个具体的框架或者库更像是一种项目组织思路——把偏艺术化的视觉表达和偏工程化的代码实现用一套轻量的结构串起来让一个人或者小团队也能做出有设计感、又能跑得动的作品。说白了artcraft 要解决的核心痛点很朴素创意和实现之间那道鸿沟。你可能见过太多这样的情况——设计师出了一版很漂亮的视觉稿前端拿到手发现动效根本没法还原或者一个开发者自己写了个小工具功能没问题但界面丑到没人愿意用。artcraft 这个思路想做的就是让这两件事在同一个项目里自然共存而不是互相打架。它适合谁我梳理了一下大概三类人最需要第一类是独立开发者一个人要兼顾视觉和逻辑没精力去搭复杂的工程体系第二类是创意编码爱好者喜欢用代码做视觉实验但不想被重型框架绑住第三类是小团队里的全栈角色需要一套大家都能看懂的目录约定减少沟通成本。不管你之前是偏设计还是偏开发artcraft 这套思路都能让你在自己的舒适区边缘往外迈一步。我后面会从整体设计思路、核心细节、实操流程、常见坑四个维度把 artcraft 这类项目怎么落地讲透。内容会尽量贴近真实操作参数和步骤都给到能直接抄的程度。2. 整体设计与思路拆解为什么这样组织项目2.1 核心思路把“艺术层”和“工艺层”显式分开artcraft 最核心的一个设计决策是在项目结构上就把视觉资产和逻辑代码分成两个平行的层。我见过太多项目把图片、样式、脚本全塞在一个assets文件夹里时间一长就变成垃圾场。artcraft 的做法是art/目录专门放视觉相关的原始资产设计稿、配色方案、字体文件、纹理素材、动效曲线定义。craft/目录专门放工程实现组件逻辑、状态管理、构建脚本、工具函数。两者之间通过一份约定好的接口描述来通信比如一份theme.json或者tokens.css把颜色、间距、圆角、动效时长这些“设计决策”变成代码能读的变量。这么做的理由很直接视觉变更是高频的逻辑变更是低频的。把高频变更的东西隔离出来改配色的时候就不用去翻组件代码改逻辑的时候也不会误删设计资源。我实测下来这种分离让改版效率至少提升一倍尤其是那种“老板觉得颜色再调调”的需求改一个 token 文件就全站生效。2.2 方案选型为什么不用重型框架有人会问直接用现成的大框架不香吗我的经验是artcraft 这类项目通常体量小、迭代快、视觉要求高重型框架带来的抽象层反而会成为负担。举个例子一个用代码生成动态海报的小工具核心逻辑可能就几百行但视觉上要精确控制每一个像素的偏移和缓动。这时候引入一套完整的组件生命周期和虚拟 DOM纯属杀鸡用牛刀。artcraft 更倾向于原生能力加轻量工具链的组合渲染层直接用 Canvas 2D 或者 SVG需要 3D 再上 WebGL不额外包一层。构建用 Vite 或者 esbuild启动快、配置少。状态管理能不用就不用实在需要就用一个几十行的发布订阅模式。注意轻量不等于简陋。选轻量方案的前提是你对底层 API 足够熟悉否则遇到问题连排查方向都没有。如果你是刚入门建议先用成熟框架把项目跑通再逐步替换成轻量方案。2.3 优势与代价这套思路的边界在哪任何方案都有取舍artcraft 这套思路的优势和代价我列个表对比一下方便你判断适不适合自己的场景。维度优势代价改版效率视觉与逻辑分离改配色/字体不动代码需要维护一份接口描述文件初期有约定成本学习曲线概念少会 JS 和 CSS 就能上手底层 API 细节多出问题排查靠经验包体积依赖少产物通常几十 KB 级别复杂交互需要自己造轮子团队协作目录约定清晰设计和开发各管各的约定靠自觉没有框架强制约束可移植性不绑定特定框架换技术栈成本低生态工具少很多事要自己写我个人的判断是单人项目、视觉驱动型项目、教学演示类项目最适合 artcraft 思路多人协作的中大型业务系统还是老老实实用成熟框架别给自己找麻烦。3. 核心细节解析与实操要点把约定变成可执行的规则3.1 目录结构一份可以直接抄的骨架光说思路没用得落到具体目录上。下面这份结构是我在多个 artcraft 类项目里反复调整后沉淀下来的你可以直接拿去用project-root/ ├── art/ │ ├── tokens/ │ │ ├── colors.json │ │ ├── spacing.json │ │ └── motion.json │ ├── assets/ │ │ ├── textures/ │ │ └── fonts/ │ └── references/ │ └── moodboard.md ├── craft/ │ ├── core/ │ │ ├── renderer.js │ │ └── loop.js │ ├── components/ │ └── utils/ ├── public/ ├── index.html ├── vite.config.js └── package.json关键点在于art/tokens/这一层。它把设计决策从“感觉”变成“数据”。比如colors.json里不是写#3A7BD5就完事而是带上语义{ primary: { value: #3A7BD5, usage: 主操作按钮、强调文字 }, surface: { value: #F7F9FC, usage: 卡片背景、页面底色 }, accent: { value: #FF6B6B, usage: 警示、高亮标记 } }这样做的价值在于半年后你回来看这个项目能立刻知道每个颜色是干嘛的而不是对着一堆十六进制值发呆。motion.json同理把缓动曲线和时长命名成enter、exit、emphasis代码里引用名字而不是魔法数字。3.2 接口描述让设计和代码说同一种语言artcraft 里最容易出问题的环节就是视觉资产和代码之间的“翻译”。我的做法是只维护一份 token 源文件其他全部自动生成。具体流程在art/tokens/下维护 JSON 源文件这是唯一手动编辑的地方。写一个构建脚本把 JSON 转成 CSS 变量和 JS 常量两份产物。组件里引用 CSS 变量做样式引用 JS 常量做 Canvas 绘制。转换脚本核心逻辑大概长这样// scripts/build-tokens.js import fs from fs; import path from path; const tokensDir path.resolve(art/tokens); const outDir path.resolve(craft/generated); const colors JSON.parse(fs.readFileSync(path.join(tokensDir, colors.json), utf-8)); // 生成 CSS 变量 let cssVars :root {\n; for (const [name, def] of Object.entries(colors)) { cssVars --color-${name}: ${def.value};\n; } cssVars }\n; fs.writeFileSync(path.join(outDir, tokens.css), cssVars); // 生成 JS 常量 const jsConst export const COLORS ${JSON.stringify( Object.fromEntries(Object.entries(colors).map(([k, v]) [k, v.value])), null, 2 )};\n; fs.writeFileSync(path.join(outDir, tokens.js), jsConst);提示生成产物要加进.gitignore只提交源文件。否则每次改 token 都会产生一堆 diffreview 的时候很痛苦。3.3 渲染循环artcraft 项目的心脏视觉驱动型项目基本都绕不开一个渲染循环。不管你是做动画、做交互可视化还是做生成艺术核心都是一个requestAnimationFrame驱动的循环。artcraft 思路下这个循环要写得足够干净方便随时插入新的绘制逻辑。我常用的骨架是这样的// craft/core/loop.js export function createLoop(update, render) { let lastTime 0; let running false; function frame(now) { if (!running) return; const delta now - lastTime; lastTime now; update(delta); render(); requestAnimationFrame(frame); } return { start() { if (running) return; running true; lastTime performance.now(); requestAnimationFrame(frame); }, stop() { running false; } }; }这里有几个细节值得说。第一delta用毫秒而不是帧数这样在不同刷新率的屏幕上动画速度一致。第二update和render分开逻辑更新和绘制解耦方便做暂停、快进、录制。第三running标志位防止重复启动我见过不少项目因为没做这个判断导致多个循环叠加性能直接崩掉。3.4 视觉资产的预处理别把原始文件直接扔进项目artcraft 项目里视觉资产往往很多纹理、字体、图标、参考图。我的经验是原始文件永远不要直接进构建流程中间加一层预处理图片统一转成 WebP保留一份 PNG 作为降级。字体做子集化只保留用到的字符一个中文字体动辄几 MB子集化后能降到几十 KB。纹理图做尺寸压缩根据实际显示尺寸的 2 倍导出兼顾清晰度和体积。预处理脚本可以挂在prebuild钩子上每次构建自动跑。这一步看起来麻烦但省下来的是用户的加载时间值得。4. 实操过程与核心环节实现从零搭一个 artcraft 项目4.1 环境准备与依赖安装假设你已经装好了 Node.js建议 18 以上新建目录后执行npm init -y npm install -D vite npm install -D sharpvite负责开发和构建sharp负责图片预处理。为什么选 Vite 而不是别的因为它的开发服务器启动是毫秒级的改一行代码几乎瞬间看到效果这对视觉调试太重要了。sharp是 Node 生态里处理图片性能最好的库之一批量压缩纹理用它很稳。装完之后在package.json里加几个脚本{ scripts: { dev: vite, build: node scripts/preprocess-assets.js vite build, tokens: node scripts/build-tokens.js } }4.2 初始化目录与 token 文件按第 3.1 节的结构把目录建好然后创建第一份 token 文件。我建议从颜色和间距开始动效 token 可以等项目有动画需求了再加。spacing.json的写法{ xs: { value: 4px, usage: 图标与文字间距 }, sm: { value: 8px, usage: 紧凑元素间距 }, md: { value: 16px, usage: 常规内边距 }, lg: { value: 32px, usage: 区块间距 }, xl: { value: 64px, usage: 页面级留白 } }跑一次npm run tokens检查craft/generated/下有没有生成对应的 CSS 和 JS 文件。这一步跑通说明你的 token 流水线是活的。4.3 搭建渲染入口在index.html里放一个全屏 canvas!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 titleartcraft demo/title link relstylesheet href/craft/generated/tokens.css style html, body { margin: 0; height: 100%; overflow: hidden; } #stage { display: block; width: 100%; height: 100%; } /style /head body canvas idstage/canvas script typemodule src/craft/main.js/script /body /html然后在craft/main.js里把渲染循环接上import { createLoop } from ./core/loop.js; import { COLORS } from ./generated/tokens.js; const canvas document.getElementById(stage); const ctx canvas.getContext(2d); function resize() { const dpr window.devicePixelRatio || 1; canvas.width canvas.clientWidth * dpr; canvas.height canvas.clientHeight * dpr; ctx.scale(dpr, dpr); } window.addEventListener(resize, resize); resize(); let angle 0; const loop createLoop( (delta) { angle delta * 0.001; }, () { const w canvas.clientWidth; const h canvas.clientHeight; ctx.clearRect(0, 0, w, h); ctx.fillStyle COLORS.surface; ctx.fillRect(0, 0, w, h); ctx.save(); ctx.translate(w / 2, h / 2); ctx.rotate(angle); ctx.fillStyle COLORS.primary; ctx.fillRect(-40, -40, 80, 80); ctx.restore(); } ); loop.start();这段代码跑起来你会看到一个缓慢旋转的方块背景色和方块色都来自 token 文件。改colors.json里的值刷新页面颜色立刻变——这就是 artcraft 思路最直观的收益。4.4 参数计算DPR 缩放为什么必须做上面resize函数里的devicePixelRatio处理是很多新手会忽略的点。简单解释一下现在的高分屏一个 CSS 像素对应多个物理像素如果 canvas 的width直接设成 CSS 宽度绘制出来的图形在高分屏上会发虚。正确做法是把 canvas 的实际像素尺寸乘以 DPR再用ctx.scale(dpr, dpr)把坐标系缩回来这样你写代码时还是按 CSS 像素思考但输出是清晰的。举个例子一个 400×300 的 canvas在 DPR 为 2 的屏幕上实际像素尺寸要设成 800×600然后 scale(2, 2)。这样你画一个 100×100 的矩形物理上占 200×200 像素边缘锐利。不做这一步图形边缘就会糊尤其是细线和文字。4.5 资产预处理脚本实现scripts/preprocess-assets.js的核心逻辑import fs from fs; import path from path; import sharp from sharp; const srcDir path.resolve(art/assets/textures); const outDir path.resolve(public/textures); if (!fs.existsSync(outDir)) fs.mkdirSync(outDir, { recursive: true }); const files fs.readdirSync(srcDir).filter(f /\.(png|jpg|jpeg)$/i.test(f)); for (const file of files) { const name path.parse(file).name; await sharp(path.join(srcDir, file)) .resize({ width: 1024, withoutEnlargement: true }) .webp({ quality: 82 }) .toFile(path.join(outDir, ${name}.webp)); console.log(processed: ${file}); }quality: 82是我反复测试后觉得性价比最高的值再高体积涨得快再低肉眼能看出块状。withoutEnlargement防止小图被强行放大这个坑我踩过一张 200px 的纹理被拉到 1024px糊得没法看。5. 常见问题与排查技巧实录5.1 画面模糊、锯齿严重这是最高频的问题排查顺序我整理成表现象可能原因排查方法解决整体发虚没做 DPR 缩放打印devicePixelRatio按 4.4 节处理边缘锯齿没开抗锯齿检查ctx.imageSmoothingEnabled设为 true文字模糊字体未子集化或尺寸非整数检查字号是否带小数字号取整图片糊源图分辨率不足对比源图和显示尺寸换 2 倍图我遇到过一次特别隐蔽的canvas 的 CSS 宽度是100%但父容器有padding导致clientWidth和实际可视区域对不上图形被拉伸。后来改成用getBoundingClientRect()取尺寸才解决。凡是涉及尺寸的地方优先用getBoundingClientRect别信clientWidth。5.2 动画卡顿、掉帧卡顿的根源通常是每帧做了不该做的事。常见的有在render里创建对象比如每帧new Path2D()触发频繁 GC。在update里做 DOM 查询布局抖动。绘制了大量离屏内容却没做缓存。我的做法是把不变的东西缓存成离屏 canvas每帧只做合成。比如一个复杂的背景纹理第一次绘制到离屏 canvas之后每帧直接drawImage贴上去性能能差出好几倍。另外requestAnimationFrame的回调里避免任何console.log这玩意儿在大量输出时会明显拖慢帧率调试完记得删。5.3 token 改了但页面没变这个问题的排查链路比较固定确认npm run tokens跑过了craft/generated/下的文件时间戳是新的。确认代码里引用的是生成产物而不是硬编码的值。确认 Vite 的 HMR 有没有生效有时候需要手动刷新。检查浏览器缓存CSS 变量可能被缓存了。我建议在build-tokens.js里加一行日志输出生成了哪些文件、各多少个变量这样一眼就能看出脚本有没有正常执行。别小看这行日志省下的排查时间很可观。5.4 字体加载闪烁自定义字体在 artcraft 项目里很常见但加载时机不对会导致文字先以默认字体显示然后突然跳变。解决办法有两个一是用font-display: swap配合预加载二是干脆等字体加载完再启动渲染循环。我倾向于后者因为视觉项目对首屏一致性要求高宁可多等 100ms 也不要闪烁。await document.fonts.load(16px MyFont); loop.start();5.5 构建产物过大如果构建出来超过几百 KB先看是不是把原始资产打进去了。检查public/目录确保里面只有预处理后的产物没有原始大图。另外art/references/这种参考目录要排除在构建之外Vite 默认会打包public下的所有东西参考图放进去就是灾难。注意art/目录整体不应该进入构建产物它只是源文件。构建时只读取craft/generated/和public/。6. 我在这类项目里踩过的坑和总结的经验做 artcraft 类项目这几年有几个教训是用真金白银的时间换来的分享出来希望能帮你少走弯路。第一个是别过早追求完美架构。我一开始总想把 token 系统设计得无比完备支持嵌套、别名、主题切换结果光设计这套东西就花了一周项目本身还没动。后来想通了先跑起来再重构。第一版 token 就三个文件、几十个变量够用就行等真的遇到扩展需求再加。第二个是视觉调试要留后门。我在项目里常驻一个调试面板按个快捷键就能调出当前所有 token 的值还能实时改。这个面板只在开发环境加载生产环境自动剔除。有了它调间距、调颜色不用来回改文件刷新效率提升非常明显。第三个是性能问题要早发现。视觉项目很容易在后期堆出性能瓶颈等发现卡顿再回头优化改动面会很大。我的做法是从第一天就盯着帧率在循环里加一个简单的 FPS 统计低于 55 就警觉。早发现早处理成本低得多。第四个是文档写在代码旁边。artcraft 项目的约定很多目录结构、token 命名、接口格式这些如果只存在脑子里过两个月自己都忘。我的习惯是在每个关键目录放一个README.md几行字说明这个目录放什么、命名规则是什么。别指望写一份大而全的文档那种东西没人看就近说明才有效。最后说一个心态上的体会artcraft 这类项目最大的魅力在于它让你同时是设计师和工程师。你调一个颜色立刻能看到整个画面的变化你写一段逻辑立刻能变成看得见的动效。这种即时反馈是纯业务开发很难体会到的。但也正因为如此很容易陷入“再调一点点”的无限循环。给自己设个时间盒比如视觉调试不超过总时间的 30%剩下的留给逻辑和性能项目才能真的做完。如果你也在做类似的项目欢迎按上面的结构搭一遍遇到问题对照第 5 节的排查表走一遍大部分坑都能填上。这套东西不复杂难的是坚持把约定执行下去。 
长河君 · 2026/10/21 9:29:11 · 阅读 1.2k artcraft项目组织思路：轻量分离视觉与逻辑的独立开发实践
1. 从“artcraft”这个名字说起它到底想解决什么问题第一次看到“artcraft”这个标题我脑子里蹦出来的第一反应是“艺术”加“手艺”一个把创意和动手能力揉在一起的东西。后来跟几个做独立开发的朋友聊发现大家对这个词的理解出奇地一致它不是一个具体的框架或者库更像是一种项目组织思路——把偏艺术化的视觉表达和偏工程化的代码实现用一套轻量的结构串起来让一个人或者小团队也能做出有设计感、又能跑得动的作品。说白了artcraft 要解决的核心痛点很朴素创意和实现之间那道鸿沟。你可能见过太多这样的情况——设计师出了一版很漂亮的视觉稿前端拿到手发现动效根本没法还原或者一个开发者自己写了个小工具功能没问题但界面丑到没人愿意用。artcraft 这个思路想做的就是让这两件事在同一个项目里自然共存而不是互相打架。它适合谁我梳理了一下大概三类人最需要第一类是独立开发者一个人要兼顾视觉和逻辑没精力去搭复杂的工程体系第二类是创意编码爱好者喜欢用代码做视觉实验但不想被重型框架绑住第三类是小团队里的全栈角色需要一套大家都能看懂的目录约定减少沟通成本。不管你之前是偏设计还是偏开发artcraft 这套思路都能让你在自己的舒适区边缘往外迈一步。我后面会从整体设计思路、核心细节、实操流程、常见坑四个维度把 artcraft 这类项目怎么落地讲透。内容会尽量贴近真实操作参数和步骤都给到能直接抄的程度。2. 整体设计与思路拆解为什么这样组织项目2.1 核心思路把“艺术层”和“工艺层”显式分开artcraft 最核心的一个设计决策是在项目结构上就把视觉资产和逻辑代码分成两个平行的层。我见过太多项目把图片、样式、脚本全塞在一个assets文件夹里时间一长就变成垃圾场。artcraft 的做法是art/目录专门放视觉相关的原始资产设计稿、配色方案、字体文件、纹理素材、动效曲线定义。craft/目录专门放工程实现组件逻辑、状态管理、构建脚本、工具函数。两者之间通过一份约定好的接口描述来通信比如一份theme.json或者tokens.css把颜色、间距、圆角、动效时长这些“设计决策”变成代码能读的变量。这么做的理由很直接视觉变更是高频的逻辑变更是低频的。把高频变更的东西隔离出来改配色的时候就不用去翻组件代码改逻辑的时候也不会误删设计资源。我实测下来这种分离让改版效率至少提升一倍尤其是那种“老板觉得颜色再调调”的需求改一个 token 文件就全站生效。2.2 方案选型为什么不用重型框架有人会问直接用现成的大框架不香吗我的经验是artcraft 这类项目通常体量小、迭代快、视觉要求高重型框架带来的抽象层反而会成为负担。举个例子一个用代码生成动态海报的小工具核心逻辑可能就几百行但视觉上要精确控制每一个像素的偏移和缓动。这时候引入一套完整的组件生命周期和虚拟 DOM纯属杀鸡用牛刀。artcraft 更倾向于原生能力加轻量工具链的组合渲染层直接用 Canvas 2D 或者 SVG需要 3D 再上 WebGL不额外包一层。构建用 Vite 或者 esbuild启动快、配置少。状态管理能不用就不用实在需要就用一个几十行的发布订阅模式。注意轻量不等于简陋。选轻量方案的前提是你对底层 API 足够熟悉否则遇到问题连排查方向都没有。如果你是刚入门建议先用成熟框架把项目跑通再逐步替换成轻量方案。2.3 优势与代价这套思路的边界在哪任何方案都有取舍artcraft 这套思路的优势和代价我列个表对比一下方便你判断适不适合自己的场景。维度优势代价改版效率视觉与逻辑分离改配色/字体不动代码需要维护一份接口描述文件初期有约定成本学习曲线概念少会 JS 和 CSS 就能上手底层 API 细节多出问题排查靠经验包体积依赖少产物通常几十 KB 级别复杂交互需要自己造轮子团队协作目录约定清晰设计和开发各管各的约定靠自觉没有框架强制约束可移植性不绑定特定框架换技术栈成本低生态工具少很多事要自己写我个人的判断是单人项目、视觉驱动型项目、教学演示类项目最适合 artcraft 思路多人协作的中大型业务系统还是老老实实用成熟框架别给自己找麻烦。3. 核心细节解析与实操要点把约定变成可执行的规则3.1 目录结构一份可以直接抄的骨架光说思路没用得落到具体目录上。下面这份结构是我在多个 artcraft 类项目里反复调整后沉淀下来的你可以直接拿去用project-root/ ├── art/ │ ├── tokens/ │ │ ├── colors.json │ │ ├── spacing.json │ │ └── motion.json │ ├── assets/ │ │ ├── textures/ │ │ └── fonts/ │ └── references/ │ └── moodboard.md ├── craft/ │ ├── core/ │ │ ├── renderer.js │ │ └── loop.js │ ├── components/ │ └── utils/ ├── public/ ├── index.html ├── vite.config.js └── package.json关键点在于art/tokens/这一层。它把设计决策从“感觉”变成“数据”。比如colors.json里不是写#3A7BD5就完事而是带上语义{ primary: { value: #3A7BD5, usage: 主操作按钮、强调文字 }, surface: { value: #F7F9FC, usage: 卡片背景、页面底色 }, accent: { value: #FF6B6B, usage: 警示、高亮标记 } }这样做的价值在于半年后你回来看这个项目能立刻知道每个颜色是干嘛的而不是对着一堆十六进制值发呆。motion.json同理把缓动曲线和时长命名成enter、exit、emphasis代码里引用名字而不是魔法数字。3.2 接口描述让设计和代码说同一种语言artcraft 里最容易出问题的环节就是视觉资产和代码之间的“翻译”。我的做法是只维护一份 token 源文件其他全部自动生成。具体流程在art/tokens/下维护 JSON 源文件这是唯一手动编辑的地方。写一个构建脚本把 JSON 转成 CSS 变量和 JS 常量两份产物。组件里引用 CSS 变量做样式引用 JS 常量做 Canvas 绘制。转换脚本核心逻辑大概长这样// scripts/build-tokens.js import fs from fs; import path from path; const tokensDir path.resolve(art/tokens); const outDir path.resolve(craft/generated); const colors JSON.parse(fs.readFileSync(path.join(tokensDir, colors.json), utf-8)); // 生成 CSS 变量 let cssVars :root {\n; for (const [name, def] of Object.entries(colors)) { cssVars --color-${name}: ${def.value};\n; } cssVars }\n; fs.writeFileSync(path.join(outDir, tokens.css), cssVars); // 生成 JS 常量 const jsConst export const COLORS ${JSON.stringify( Object.fromEntries(Object.entries(colors).map(([k, v]) [k, v.value])), null, 2 )};\n; fs.writeFileSync(path.join(outDir, tokens.js), jsConst);提示生成产物要加进.gitignore只提交源文件。否则每次改 token 都会产生一堆 diffreview 的时候很痛苦。3.3 渲染循环artcraft 项目的心脏视觉驱动型项目基本都绕不开一个渲染循环。不管你是做动画、做交互可视化还是做生成艺术核心都是一个requestAnimationFrame驱动的循环。artcraft 思路下这个循环要写得足够干净方便随时插入新的绘制逻辑。我常用的骨架是这样的// craft/core/loop.js export function createLoop(update, render) { let lastTime 0; let running false; function frame(now) { if (!running) return; const delta now - lastTime; lastTime now; update(delta); render(); requestAnimationFrame(frame); } return { start() { if (running) return; running true; lastTime performance.now(); requestAnimationFrame(frame); }, stop() { running false; } }; }这里有几个细节值得说。第一delta用毫秒而不是帧数这样在不同刷新率的屏幕上动画速度一致。第二update和render分开逻辑更新和绘制解耦方便做暂停、快进、录制。第三running标志位防止重复启动我见过不少项目因为没做这个判断导致多个循环叠加性能直接崩掉。3.4 视觉资产的预处理别把原始文件直接扔进项目artcraft 项目里视觉资产往往很多纹理、字体、图标、参考图。我的经验是原始文件永远不要直接进构建流程中间加一层预处理图片统一转成 WebP保留一份 PNG 作为降级。字体做子集化只保留用到的字符一个中文字体动辄几 MB子集化后能降到几十 KB。纹理图做尺寸压缩根据实际显示尺寸的 2 倍导出兼顾清晰度和体积。预处理脚本可以挂在prebuild钩子上每次构建自动跑。这一步看起来麻烦但省下来的是用户的加载时间值得。4. 实操过程与核心环节实现从零搭一个 artcraft 项目4.1 环境准备与依赖安装假设你已经装好了 Node.js建议 18 以上新建目录后执行npm init -y npm install -D vite npm install -D sharpvite负责开发和构建sharp负责图片预处理。为什么选 Vite 而不是别的因为它的开发服务器启动是毫秒级的改一行代码几乎瞬间看到效果这对视觉调试太重要了。sharp是 Node 生态里处理图片性能最好的库之一批量压缩纹理用它很稳。装完之后在package.json里加几个脚本{ scripts: { dev: vite, build: node scripts/preprocess-assets.js vite build, tokens: node scripts/build-tokens.js } }4.2 初始化目录与 token 文件按第 3.1 节的结构把目录建好然后创建第一份 token 文件。我建议从颜色和间距开始动效 token 可以等项目有动画需求了再加。spacing.json的写法{ xs: { value: 4px, usage: 图标与文字间距 }, sm: { value: 8px, usage: 紧凑元素间距 }, md: { value: 16px, usage: 常规内边距 }, lg: { value: 32px, usage: 区块间距 }, xl: { value: 64px, usage: 页面级留白 } }跑一次npm run tokens检查craft/generated/下有没有生成对应的 CSS 和 JS 文件。这一步跑通说明你的 token 流水线是活的。4.3 搭建渲染入口在index.html里放一个全屏 canvas!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 titleartcraft demo/title link relstylesheet href/craft/generated/tokens.css style html, body { margin: 0; height: 100%; overflow: hidden; } #stage { display: block; width: 100%; height: 100%; } /style /head body canvas idstage/canvas script typemodule src/craft/main.js/script /body /html然后在craft/main.js里把渲染循环接上import { createLoop } from ./core/loop.js; import { COLORS } from ./generated/tokens.js; const canvas document.getElementById(stage); const ctx canvas.getContext(2d); function resize() { const dpr window.devicePixelRatio || 1; canvas.width canvas.clientWidth * dpr; canvas.height canvas.clientHeight * dpr; ctx.scale(dpr, dpr); } window.addEventListener(resize, resize); resize(); let angle 0; const loop createLoop( (delta) { angle delta * 0.001; }, () { const w canvas.clientWidth; const h canvas.clientHeight; ctx.clearRect(0, 0, w, h); ctx.fillStyle COLORS.surface; ctx.fillRect(0, 0, w, h); ctx.save(); ctx.translate(w / 2, h / 2); ctx.rotate(angle); ctx.fillStyle COLORS.primary; ctx.fillRect(-40, -40, 80, 80); ctx.restore(); } ); loop.start();这段代码跑起来你会看到一个缓慢旋转的方块背景色和方块色都来自 token 文件。改colors.json里的值刷新页面颜色立刻变——这就是 artcraft 思路最直观的收益。4.4 参数计算DPR 缩放为什么必须做上面resize函数里的devicePixelRatio处理是很多新手会忽略的点。简单解释一下现在的高分屏一个 CSS 像素对应多个物理像素如果 canvas 的width直接设成 CSS 宽度绘制出来的图形在高分屏上会发虚。正确做法是把 canvas 的实际像素尺寸乘以 DPR再用ctx.scale(dpr, dpr)把坐标系缩回来这样你写代码时还是按 CSS 像素思考但输出是清晰的。举个例子一个 400×300 的 canvas在 DPR 为 2 的屏幕上实际像素尺寸要设成 800×600然后 scale(2, 2)。这样你画一个 100×100 的矩形物理上占 200×200 像素边缘锐利。不做这一步图形边缘就会糊尤其是细线和文字。4.5 资产预处理脚本实现scripts/preprocess-assets.js的核心逻辑import fs from fs; import path from path; import sharp from sharp; const srcDir path.resolve(art/assets/textures); const outDir path.resolve(public/textures); if (!fs.existsSync(outDir)) fs.mkdirSync(outDir, { recursive: true }); const files fs.readdirSync(srcDir).filter(f /\.(png|jpg|jpeg)$/i.test(f)); for (const file of files) { const name path.parse(file).name; await sharp(path.join(srcDir, file)) .resize({ width: 1024, withoutEnlargement: true }) .webp({ quality: 82 }) .toFile(path.join(outDir, ${name}.webp)); console.log(processed: ${file}); }quality: 82是我反复测试后觉得性价比最高的值再高体积涨得快再低肉眼能看出块状。withoutEnlargement防止小图被强行放大这个坑我踩过一张 200px 的纹理被拉到 1024px糊得没法看。5. 常见问题与排查技巧实录5.1 画面模糊、锯齿严重这是最高频的问题排查顺序我整理成表现象可能原因排查方法解决整体发虚没做 DPR 缩放打印devicePixelRatio按 4.4 节处理边缘锯齿没开抗锯齿检查ctx.imageSmoothingEnabled设为 true文字模糊字体未子集化或尺寸非整数检查字号是否带小数字号取整图片糊源图分辨率不足对比源图和显示尺寸换 2 倍图我遇到过一次特别隐蔽的canvas 的 CSS 宽度是100%但父容器有padding导致clientWidth和实际可视区域对不上图形被拉伸。后来改成用getBoundingClientRect()取尺寸才解决。凡是涉及尺寸的地方优先用getBoundingClientRect别信clientWidth。5.2 动画卡顿、掉帧卡顿的根源通常是每帧做了不该做的事。常见的有在render里创建对象比如每帧new Path2D()触发频繁 GC。在update里做 DOM 查询布局抖动。绘制了大量离屏内容却没做缓存。我的做法是把不变的东西缓存成离屏 canvas每帧只做合成。比如一个复杂的背景纹理第一次绘制到离屏 canvas之后每帧直接drawImage贴上去性能能差出好几倍。另外requestAnimationFrame的回调里避免任何console.log这玩意儿在大量输出时会明显拖慢帧率调试完记得删。5.3 token 改了但页面没变这个问题的排查链路比较固定确认npm run tokens跑过了craft/generated/下的文件时间戳是新的。确认代码里引用的是生成产物而不是硬编码的值。确认 Vite 的 HMR 有没有生效有时候需要手动刷新。检查浏览器缓存CSS 变量可能被缓存了。我建议在build-tokens.js里加一行日志输出生成了哪些文件、各多少个变量这样一眼就能看出脚本有没有正常执行。别小看这行日志省下的排查时间很可观。5.4 字体加载闪烁自定义字体在 artcraft 项目里很常见但加载时机不对会导致文字先以默认字体显示然后突然跳变。解决办法有两个一是用font-display: swap配合预加载二是干脆等字体加载完再启动渲染循环。我倾向于后者因为视觉项目对首屏一致性要求高宁可多等 100ms 也不要闪烁。await document.fonts.load(16px MyFont); loop.start();5.5 构建产物过大如果构建出来超过几百 KB先看是不是把原始资产打进去了。检查public/目录确保里面只有预处理后的产物没有原始大图。另外art/references/这种参考目录要排除在构建之外Vite 默认会打包public下的所有东西参考图放进去就是灾难。注意art/目录整体不应该进入构建产物它只是源文件。构建时只读取craft/generated/和public/。6. 我在这类项目里踩过的坑和总结的经验做 artcraft 类项目这几年有几个教训是用真金白银的时间换来的分享出来希望能帮你少走弯路。第一个是别过早追求完美架构。我一开始总想把 token 系统设计得无比完备支持嵌套、别名、主题切换结果光设计这套东西就花了一周项目本身还没动。后来想通了先跑起来再重构。第一版 token 就三个文件、几十个变量够用就行等真的遇到扩展需求再加。第二个是视觉调试要留后门。我在项目里常驻一个调试面板按个快捷键就能调出当前所有 token 的值还能实时改。这个面板只在开发环境加载生产环境自动剔除。有了它调间距、调颜色不用来回改文件刷新效率提升非常明显。第三个是性能问题要早发现。视觉项目很容易在后期堆出性能瓶颈等发现卡顿再回头优化改动面会很大。我的做法是从第一天就盯着帧率在循环里加一个简单的 FPS 统计低于 55 就警觉。早发现早处理成本低得多。第四个是文档写在代码旁边。artcraft 项目的约定很多目录结构、token 命名、接口格式这些如果只存在脑子里过两个月自己都忘。我的习惯是在每个关键目录放一个README.md几行字说明这个目录放什么、命名规则是什么。别指望写一份大而全的文档那种东西没人看就近说明才有效。最后说一个心态上的体会artcraft 这类项目最大的魅力在于它让你同时是设计师和工程师。你调一个颜色立刻能看到整个画面的变化你写一段逻辑立刻能变成看得见的动效。这种即时反馈是纯业务开发很难体会到的。但也正因为如此很容易陷入“再调一点点”的无限循环。给自己设个时间盒比如视觉调试不超过总时间的 30%剩下的留给逻辑和性能项目才能真的做完。如果你也在做类似的项目欢迎按上面的结构搭一遍遇到问题对照第 5 节的排查表走一遍大部分坑都能填上。这套东西不复杂难的是坚持把约定执行下去。