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 都会产生一堆 diff，review 的时候很痛苦。
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 lang="zh-CN"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>artcraft demo</title> <link rel="stylesheet" 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 id="stage"></canvas> <script type="module" 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 节的排查表走一遍，大部分坑都能填上。这套东西不复杂，难的是坚持把约定执行下去。
