ImageCraft：全功能图片批处理工具 — 从技术实现到架构设计

ImageCraft：全功能图片批处理工具 — 从技术实现到架构设计

一、背景与概述

在日常开发和内容创作中，图片处理是一个高频需求：调整尺寸、压缩体积、格式转换、添加水印、应用滤镜……这些操作看似简单，但要做好却需要一套完整的工具链。

ImageCraft 是一个基于 Web 的全功能图片处理工具，提供图形化界面，让用户无需编写代码即可完成复杂的图片处理任务。它采用 React + TypeScript 构建前端，Express + Sharp 构建后端，支持单张处理和批量处理，并内置了 18 种常用尺寸模板。

项目地址：https://toolion.cn/imagecraft/

二、核心功能

2.1 图片处理

2.2 尺寸模板

内置 18 种常用尺寸模板，覆盖各大平台：

• 社交类：微信封面（900×383）、小红书封面（1242×1660）、抖音封面（1080×1920）、Instagram 帖子（1080×1080）、Twitter 头图（1500×500）
• 电商类：淘宝主图（800×800）、京东主图（800×800）、Amazon 主图（2000×2000）
• 印刷类：A4 竖版/横版（300dpi）
• 屏幕类：HD 1080P、HD 720P、4K UHD

2.3 批量处理

支持选择多张图片，一次性应用相同的处理参数，打包为 ZIP 文件下载。批量处理上限根据订阅计划动态调整。

三、技术架构

3.1 前端架构

前端采用 React 19 + TypeScript + Vite 构建，使用 Tailwind CSS 进行样式管理，React Icons 提供图标支持。

apps/imagecraft/
├── src/
│ ├── App.tsx # 主应用组件
│ ├── main.tsx # 入口文件
│ ├── index.css # 全局样式
│ └── env.d.ts # 类型声明

核心设计模式：

• 状态管理：使用 React useState + useCallback 管理应用状态，通过 useRef 管理 DOM 引用
• 主题系统：支持亮色/暗色模式，通过 data-theme 属性切换，内置深色和浅色两套颜色变量
• 国际化：内置中英文切换，通过 t(zh, en) 函数实现
• 响应式布局：使用 Tailwind 的 sm:、md:、lg: 前缀实现移动端适配

3.2 后端架构

后端采用 Express + TypeScript 构建，核心图片处理基于 Sharp 库。

src/
├── controllers/
│ └── image.controller.ts # 图片处理控制器
├── middleware/
│ ├── subscription.ts # 订阅与功能守卫
│ └── auth.ts # 认证中间件
├── routes/
│ └── image.ts # 图片路由
├── services/
│ └── image/
│ ├── processor.ts # 图片处理核心
│ ├── task-queue.ts # 任务队列
│ └── storage.ts # 存储服务
├── validators/
│ └── image.ts # 请求校验
└── config/
└── index.ts # 应用配置

图片处理流水线：

输入图片 → applyResize → applyFilter → applyEnhance → applyConvert → applyMetadata → 输出

每个处理步骤都是独立的 Pipeline 操作，通过 Sharp 链式调用实现高效处理。

3.3 图片处理核心

processor.ts 是整个系统的核心，负责所有图片处理逻辑：

// 处理流水线
async process(buffer: Buffer, options: ProcessOptions): Promise<ProcessResult> {
let pipeline = sharp(buffer, { limitInputPixels: 268402689, sequentialRead: true });

pipeline = this.applyResize(pipeline, options.resize);
pipeline = this.applyFilter(pipeline, options.filter);
pipeline = this.applyEnhance(pipeline, options.enhance);
pipeline = await this.applyConvert(pipeline, options.convert, options.compress);
pipeline = this.applyMetadata(pipeline, options.stripMetadata, options.keepExif);

let outputBuffer = await pipeline.toBuffer();

// 水印和叠加在编码后应用
if (options.textWatermark) {
outputBuffer = await this.applyTextWatermark(outputBuffer, options.textWatermark, imgWidth, imgHeight);
}
// … 图片水印、文字叠加同理

return { buffer: outputBuffer, format, width, height, size, originalSize, compressionRatio };
}

关键实现细节：

3.4 订阅与权限系统

系统采用基于策略的权限控制，通过 registerAppSubscription 注册每个应用的功能配置：

registerAppSubscription({
appId: 'imagecraft',
enabled: true,
freeDailyLimit: 10, // 免费用户每日处理上限
proBatchLimit: 50, // PRO 用户批量处理上限
proFeatures: [], // PRO 专属功能列表
getUsedFeatures: (req) => { /* 从请求中提取使用的功能 */ },
});

功能守卫流程：

请求 → createFeatureGuard → 检查功能是否在 proFeatures 中
→ 是 + 免费用户 → 403 拒绝
→ 否 → 继续处理

每日限流：

通过 createDailyLimitGuard 实现，基于 appUsage 表记录每日处理次数，超过限制则返回 429。

四、前端关键实现

4.1 动态文件名截断

左侧面板显示上传的图片文件名，文件名过长时自动截断为 123….jpg 格式：

const truncateFilename = (name: string, maxLen: number = 11): string => {
if (name.length <= maxLen) return name;
const dotIndex = name.lastIndexOf('.');
const ext = dotIndex > 0 ? name.slice(dotIndex) : '';
const remaining = maxLen – ext.length – 4; // 4 for "…."
if (remaining < 3) return '….' + ext;
return name.slice(0, remaining) + '….' + ext;
};

通过 ResizeObserver 监听面板宽度变化，动态计算可显示的字符数：

const maxFilenameLen = Math.max(8, Math.floor((asideWidth – 160) / 6.5));

4.2 Section 自动展开/收起

处理设置页的每个功能区块（调整尺寸、压缩、格式转换等）支持开关控制。开启时自动展开，关闭时自动收起：

const updateSetting = useCallback(<K extends keyof ProcessSettings>(
section: K,
field: keyof ProcessSettings[K],
value: any
) => {
setSettings(prev => ({
…prev,
[section]: { …prev[section], [field]: value },
}));
if (field === 'enabled') {
setExpandedSections(prev => {
const n = new Set(prev);
if (value) n.add(section);
else n.delete(section);
return n;
});
}
}, []);

4.3 工具栏响应式布局

顶部工具栏参考 CollabNote 的实现，使用 flex-wrap 实现小屏自动换行：

<header className="border-b px-3 py-1.5 sm:px-4 sm:py-2.5 flex items-center gap-2 sm:gap-3 shrink-0 flex-wrap">

五、使用指南

5.1 快速开始

六、部署与配置

6.1 环境变量

# 图片处理配置
IMAGE_MAX_FILE_SIZE=52428800 # 最大文件大小（50MB）
IMAGE_MAX_BATCH_FILES=10 # 批量上传最大文件数
IMAGECRAFT_FREE_DAILY_LIMIT=10 # 免费用户每日处理次数
IMAGECRAFT_PRO_BATCH_LIMIT=50 # PRO 用户批量处理上限

6.2 启动项目

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建生产版本
npm run build

七、总结

ImageCraft 作为一个全功能图片处理工具，核心价值在于：

项目整体代码量约 1700 行前端 + 1000 行后端，展示了如何使用现代 Web 技术栈构建一个完整的图片处理应用。

项目地址：https://toolion.cn/imagecraft/