企业官网建设流程全解析

1. 从“artcraft”这个名字说起：它到底想解决什么问题

第一次看到“artcraft”这个项目标题，我脑子里蹦出来的第一反应是“艺术”加“手艺”，听起来像是一个把创意和动手能力捏在一起的东西。后来跟几个做独立开发的朋友聊，发现大家对这个词的理解出奇地一致：它不是一个具体的框架或者库，更像是一种项目组织思路——把“艺术化的表达层”和“工程化的实现层”拆开，让两边各干各的，最后再拼起来。

这个思路解决的是一个很实际的痛点。我见过太多项目，前端代码里塞满了业务逻辑，后端接口里又硬编码了一堆展示格式，改一个按钮颜色要动三个文件，调一个接口返回要重新编译整个应用。artcraft 的核心主张就是：把“好看”和“好用”分开管。艺术部分负责视觉、交互、动效、内容编排；手艺部分负责数据、状态、路由、性能。两边通过一套约定好的契约通信，谁也别越界。

适合谁来参考？如果你正在做一个中小型创意类项目——比如个人作品集、活动落地页、轻量级互动工具、内容展示型应用——并且你既想要一定的视觉自由度，又不想把工程结构搞得太重，那 artcraft 这套思路就很对路。它不要求你上微前端，也不逼你学新框架，核心就是分层解耦四个字。下面我会把这套思路拆成可操作的步骤，从目录结构到通信机制，再到实际踩过的坑，全部摊开讲。

2. 整体设计思路：为什么要把“艺术”和“手艺”拆开

2.1 核心分层逻辑与选型考量

artcraft 的分层不是拍脑袋定的，它对应的是项目里两种完全不同的变更频率。艺术层的东西——配色、字体、间距、动效曲线、文案排版——改起来频繁且主观，今天觉得圆角好看，明天可能就想换成直角。手艺层的东西——数据获取、状态管理、路由跳转、缓存策略——改起来谨慎且客观，一旦定下来就不太动。

如果这两层混在一起，就会出现“改一个颜色导致数据请求逻辑被误伤”的惨剧。我亲身经历过一个项目，设计师要求把卡片阴影调深一点，结果开发在样式文件里顺手改了一个变量名，导致依赖这个变量的数据格式化函数报错，整个列表渲染白屏。这种问题在 artcraft 的分层下几乎不可能发生，因为艺术层根本碰不到数据逻辑。

选型上，artcraft 不绑定具体技术栈。你可以用 React + CSS Modules，也可以用 Vue + SCSS，甚至原生 JS + Canvas 都行。关键是目录结构要体现分层。我习惯的布局是这样的：

src/ art/ # 艺术层：样式、动效、布局组件、文案 styles/ animations/ layouts/ copy/ craft/ # 手艺层：数据、状态、路由、工具函数 api/ store/ router/ utils/ bridge/ # 桥接层：契约定义、事件总线、适配器 contracts/ events/ adapters/

这个结构的好处是，任何人打开项目，一眼就能看出哪些文件是“可以随便改的”，哪些是“动之前要想清楚的”。新加入的成员也不会把数据请求写到样式文件里，因为目录本身就在提醒他：你现在的改动属于哪一层。

2.2 契约先行：桥接层为什么不能省

很多人做分层做到最后就变成了“两层各写各的，最后发现对不上”。artcraft 的解法是契约先行。在写任何艺术层或手艺层代码之前，先把 bridge/contracts 里的接口定义好。比如一个作品展示模块，契约可能是这样的：

// bridge/contracts/portfolio.ts export interface PortfolioItem { id: string; title: string; coverUrl: string; tags: string[]; createdAt: number; } export interface PortfolioContract { fetchList(params: { page: number; size: number }): Promise<PortfolioItem[]>; onItemClick(item: PortfolioItem): void; }

艺术层只认这个契约，它不关心数据是从 REST API 来的还是从本地 JSON 读的。手艺层也只认这个契约，它不关心点击后是弹窗还是跳转。两边通过契约解耦，测试的时候也可以分别 mock。我试过在契约里加一个字段，艺术层和手艺层各自独立更新，最后合并时零冲突，那种顺畅感是混写代码时完全体会不到的。

注意：契约一旦定下来，修改要走评审。我见过有人为了图方便，直接在艺术层里写了个any类型绕过契约，结果手艺层改字段名时艺术层完全无感知，上线后直接报错。契约的严肃性是这套方案的生命线。

2.3 与常见架构模式的对比

有人会问，这不就是 MVC 或者 MVVM 吗？区别在于，MVC 里的 View 和 Model 通常还是通过 Controller 强耦合的，而 artcraft 的桥接层更像是一个事件总线加类型约束的组合。Controller 在 MVC 里是个大杂烩，什么逻辑都往里塞；artcraft 的 bridge 只做三件事：定义类型、转发事件、适配数据格式。它不处理业务规则，也不做条件判断。

另一个对比对象是微前端。微前端解决的是团队协作和独立部署的问题，artcraft 解决的是同一项目内部关注点分离的问题。你不需要为每个模块配一套构建工具，只需要在目录和契约上做约束。对于个人项目或小团队来说，artcraft 的 overhead 远低于微前端，但带来的结构清晰度提升是立竿见影的。

3. 核心细节解析：艺术层与手艺层各自的关键实现

3.1 艺术层的样式隔离与主题机制

艺术层最容易出的问题是样式污染。全局 CSS 一写，改一个按钮颜色可能影响到十个地方。artcraft 推荐的做法是组件级样式隔离加主题变量。具体来说，每个艺术层组件都有自己的样式文件，用 CSS Modules 或 scoped style 限制作用域，同时所有颜色、间距、字体都从主题变量里取。

主题变量的定义放在 art/styles/theme 下，结构大概是：

/* art/styles/theme/default.css */ :root { --art-color-primary: #3b82f6; --art-color-surface: #ffffff; --art-space-unit: 8px; --art-radius-card: 12px; --art-duration-fast: 150ms; --art-ease-out: cubic-bezier(0.16, 1, 0.3, 1); }

这样做的好处是，换主题只需要覆盖变量，不用改组件代码。我做过一个活动页，白天模式和夜间模式切换就是靠替换一套变量实现的，组件代码一行没动。而且变量名带art-前缀，跟手艺层的变量天然隔离，不会出现命名冲突。

实操心得：主题变量不要定义太多，我一开始定义了八十多个，后来发现常用的就二十个左右。建议先定义基础色板、间距刻度、圆角、动效时长和缓动函数这五类，不够再加。变量太多反而记不住，最后大家还是直接写死值。

3.2 手艺层的数据流与状态管理

手艺层的核心是单向数据流。数据从 api 层获取，经过 store 层处理，通过 bridge 层暴露给艺术层。艺术层永远不直接调用 api，也不直接修改 store，它只发事件。比如用户点击了一个“加载更多”按钮，艺术层发出portfolio:loadMore事件，手艺层监听后去请求数据，更新 store，再通过 bridge 通知艺术层重新渲染。

这种模式的好处是数据流向清晰，出问题时排查路径短。我遇到过一次列表不更新的 bug，按照数据流从 api 到 store 到 bridge 到 art 逐层打日志，十分钟就定位到是 bridge 层的事件名拼写错了。如果是双向绑定，这种问题可能要查半天。

状态管理工具的选择上，artcraft 不强制用 Redux 或 Pinia。小项目用一个简单的发布订阅模式就够了，几十行代码的事。大一点的项目再上成熟的状态库。关键是状态变更必须可追溯，每次变更都要有明确的触发源和日志记录。

3.3 桥接层的通信协议设计

桥接层的通信协议要解决两个问题：类型安全和异步处理。类型安全靠 TypeScript 的接口定义，异步处理靠 Promise 和事件队列。我设计的协议里，每个跨层调用都有明确的请求和响应格式：

// bridge/events/protocol.ts export interface ArtCraftEvent<T = unknown> { type: string; payload: T; timestamp: number; source: 'art' | 'craft'; } export interface ArtCraftResponse<T = unknown> { success: boolean; data?: T; error?: { code: string; message: string }; }

艺术层发事件时带上 source: 'art'，手艺层响应时带上 source: 'craft'。这样在调试时一眼就能看出消息是谁发的。timestamp 用于排查时序问题，我遇到过两个事件几乎同时发出但处理顺序反了的情况，有了时间戳就能确认是发送顺序问题还是处理队列问题。

注意：事件命名要有统一规范。我习惯用模块:动作的格式，比如portfolio:loadMore、theme:switch、modal:close。不要用驼峰或下划线混搭，否则时间一长自己都记不住。

4. 实操过程：从零搭建一个 artcraft 风格的项目

4.1 初始化目录与工具链配置

假设你要做一个个人作品展示站，用 Vite + React + TypeScript 起步。第一步不是写组件，而是把目录骨架搭好。我通常用一条命令批量创建：

mkdir -p src/art/{styles,animations,layouts,copy} \ src/craft/{api,store,router,utils} \ src/bridge/{contracts,events,adapters}

然后配置路径别名，让导入语句更清晰。在 vite.config.ts 里加：

resolve: { alias: { '@art': '/src/art', '@craft': '/src/craft', '@bridge': '/src/bridge', } }

这样在代码里import { Button } from '@art/layouts/Button'和import { fetchPortfolio } from '@craft/api/portfolio'一眼就能看出依赖的是哪一层。如果某个文件同时导入了 @art 和 @craft，那就要警惕了，它很可能违反了分层原则，应该把跨层逻辑挪到 bridge 里。

工具链上，ESLint 可以加一条自定义规则，禁止 art 目录下的文件导入 craft 目录下的文件。我用eslint-plugin-import的no-restricted-imports实现过，配置如下：

{ "rules": { "no-restricted-imports": ["error", { "patterns": [{ "group": ["@craft/*"], "message": "艺术层不能直接依赖手艺层，请通过 @bridge 通信" }] }] } }

这条规则帮我拦住了好几次无意识的越界导入。刚开始觉得麻烦，后来发现它其实是在强迫我思考“这个逻辑到底该放哪一层”，想清楚了再写，代码质量自然就上去了。

4.2 定义第一个契约并实现双向通信

以作品列表为例，先在 bridge/contracts 里定义契约：

// bridge/contracts/portfolio.ts export interface PortfolioItem { id: string; title: string; coverUrl: string; tags: string[]; } export interface PortfolioEvents { 'portfolio:load': { page: number; size: number }; 'portfolio:loaded': { items: PortfolioItem[]; total: number }; 'portfolio:error': { message: string }; }

然后在 bridge/events 里创建一个类型安全的事件总线：

// bridge/events/bus.ts type EventMap = PortfolioEvents & ThemeEvents & ModalEvents; class EventBus { private handlers = new Map<string, Set<Function>>(); on<K extends keyof EventMap>(type: K, handler: (payload: EventMap[K]) => void) { if (!this.handlers.has(type)) this.handlers.set(type, new Set()); this.handlers.get(type)!.add(handler); return () => this.handlers.get(type)!.delete(handler); } emit<K extends keyof EventMap>(type: K, payload: EventMap[K]) { this.handlers.get(type)?.forEach(fn => fn(payload)); } } export const bus = new EventBus();

手艺层监听portfolio:load，请求数据后发出portfolio:loaded。艺术层监听portfolio:loaded并渲染列表，用户点击加载更多时发出portfolio:load。整个过程中，艺术层不知道数据从哪来，手艺层不知道数据怎么展示。我实测下来，这种模式在团队协作时特别省心，前后端联调时只需要对着契约 mock 数据就行。

4.3 艺术层组件开发与动效接入

艺术层的组件开发要遵循一个原则：只接收 props，只发出事件，不处理业务逻辑。比如一个作品卡片组件：

// art/layouts/PortfolioCard.tsx import styles from './PortfolioCard.module.css'; import type { PortfolioItem } from '@bridge/contracts/portfolio'; interface Props { item: PortfolioItem; onClick: (id: string) => void; } export function PortfolioCard({ item, onClick }: Props) { return ( <div className={styles.card} onClick={() => onClick(item.id)}> <img className={styles.cover} src={item.coverUrl} alt={item.title} /> <h3 className={styles.title}>{item.title}</h3> <div className={styles.tags}> {item.tags.map(tag => <span key={tag} className={styles.tag}>{tag}</span>)} </div> </div> ); }

动效接入用 CSS 变量控制时长和缓动，方便统一调整：

.card { transition: transform var(--art-duration-fast) var(--art-ease-out), box-shadow var(--art-duration-fast) var(--art-ease-out); } .card:hover { transform: translateY(-4px); box-shadow: 0 12px 24px rgba(0, 0, 0, 0.08); }

如果要做更复杂的入场动画，可以用 Web Animations API 或者轻量的动画库，但动画逻辑要封装在 art/animations 里，不要散落在组件中。我习惯把常用的入场、退场、交错动画做成 hooks，比如useStaggerIn，组件里一行调用就行。

实操心得：动效不要贪多。我一开始给每个卡片都加了悬浮、点击、入场三种动画，结果页面看起来像在跳舞。后来砍到只保留悬浮和入场，反而更高级。动效的目的是引导注意力，不是炫技。

5. 常见问题与排查技巧实录

5.1 事件丢失与重复触发怎么查

事件丢失通常有三个原因：监听器注册太晚、事件名拼写不一致、组件卸载时没清理监听。我排查时习惯在事件总线里加日志：

emit<K extends keyof EventMap>(type: K, payload: EventMap[K]) { console.debug(`[bus] emit ${String(type)}`, payload); this.handlers.get(type)?.forEach(fn => fn(payload)); }

如果日志显示 emit 了但没触发 handler，那就是监听器没注册上。如果 handler 触发了两次，检查是不是在 useEffect 里重复注册了。React 的 StrictMode 在开发环境会故意双调用 effect，这时候要用 cleanup 函数取消监听。

重复触发还有一个隐蔽原因：事件冒泡。如果艺术层组件嵌套较深，点击事件可能冒泡到父级，导致同一个事件被发出两次。解决办法是在事件处理函数里加e.stopPropagation()，或者用自定义事件名区分层级。

5.2 样式冲突与主题切换失效的排查

样式冲突的典型表现是改了 A 组件的样式，B 组件也跟着变。先检查是不是用了全局选择器，比如div { margin: 0 }这种。artcraft 要求所有样式必须限定在组件根类名下，用 CSS Modules 的话天然隔离，但如果是全局引入的第三方样式库，就要用:where()降低优先级或者加命名空间。

主题切换失效通常是变量作用域问题。如果主题变量定义在:root上，切换时替换的是document.documentElement的类名，那所有组件都能感知。但如果某个组件把变量值写死在样式里，比如color: #3b82f6而不是color: var(--art-color-primary)，那切换主题时它就不会变。我排查时会用浏览器开发者工具检查计算样式，看最终生效的是变量还是硬编码值。

5.3 性能瓶颈的定位与优化

artcraft 分层本身不会带来性能问题，但如果桥接层事件发得太频繁，可能导致不必要的重渲染。比如滚动加载时每滚动一像素就发一次事件，那肯定卡。解决办法是加节流或防抖，在 bridge 层统一处理：

// bridge/adapters/throttle.ts export function throttle<T extends (...args: any[]) => void>(fn: T, wait: number): T { let last = 0; return ((...args: any[]) => { const now = Date.now(); if (now - last >= wait) { last = now; fn(...args); } }) as T; }

另一个性能点是艺术层的重渲染。如果列表项很多，要用虚拟滚动或者分页。我试过在艺术层用React.memo包裹卡片组件，配合稳定的 key，渲染一百个卡片毫无压力。但如果 key 用了随机数，每次渲染都重建 DOM，那就卡得没法看。

避坑技巧：每次新增一个跨层事件，先在 bridge/contracts 里加类型定义，再写发送和接收代码。不要先写实现再补类型，那样很容易漏掉字段或者类型对不上。我养成这个习惯后，跨层 bug 减少了八成以上。

6. 这套思路还能怎么扩展

artcraft 的分层思路不局限于 Web 前端。我后来把它套用到一个小程序项目上，art 层对应 WXML 和 WXSS，craft 层对应 JS 逻辑和云函数，bridge 层用自定义事件和全局状态管理。效果同样很好，尤其是多人协作时，做 UI 的和做逻辑的可以并行开发，最后按契约对接。

再往大了说，这种“艺术与手艺分离”的思想可以延伸到任何创意与工程结合的场景。比如做数据可视化，艺术层负责图表样式和交互，手艺层负责数据处理和计算，bridge 层定义数据格式和事件协议。甚至做游戏开发，渲染层和逻辑层也可以用类似的契约来解耦。

我个人在实际操作中的体会是，分层带来的最大收益不是代码好看，而是改需求时心里有底。你知道改样式不会影响数据，改数据不会破坏布局，这种确定性在项目后期尤其珍贵。当然，分层也有代价，就是前期要多写一些契约和桥接代码，项目越小这个代价越明显。我的建议是，如果项目预计超过三千行代码或者有两个人以上协作，就值得上 artcraft 这套结构；如果只是写个几十行的 demo，那就怎么快怎么来，别为了分层而分层。