1. 项目概述：一个专为汽车改装爱好者打造的轮毂Offset计算器
如果你玩过汽车改装，尤其是动过轮毂的念头，那你一定绕不开“Offset”这个参数。它直接决定了你选的轮毂装上后，是内凹出漂亮的“齐边”效果，还是凸出来蹭到翼子板，甚至影响到悬挂和转向。以前算这个，要么靠经验，要么得翻出纸笔用公式套，麻烦不说还容易出错。最近我在GitHub上看到一个叫“Offset-Calculator”的开源项目，它用现代前端技术栈（React + TypeScript + Tailwind CSS）做了一个既精准又好看的网页计算工具，特别吸引我的是它采用了当下很火的Neo-Brutalist（新粗野主义）设计风格，视觉冲击力很强。我自己也喜欢折腾这些，就决定深入研究一下这个项目，不仅复现了它的核心功能，还结合自己的实操经验，把背后的原理、开发中的技术选型考量以及一些容易踩的坑都梳理出来。无论你是前端开发者想学习一个完整的现代React应用架构，还是改装车玩家想搞明白Offset到底怎么算、怎么用，这篇文章都能给你提供一份详细的“地图”。
2. 核心需求与方案设计解析
2.1 为什么需要一个专门的Offset计算器？
在汽车改装领域，轮毂的ET值（德语Einpresstiefe，即Offset）是一个核心参数。它指的是轮毂的安装面（与刹车盘接触的面）到轮毂中心线的距离。这个数值有正有负，直接影响了轮毂在车身上的横向位置。
正Offset：安装面在中心线外侧（朝向车身外侧），轮毂看起来更“内收”。负Offset：安装面在中心线内侧（朝向车身内侧），轮毂看起来更“外凸”，也就是常说的“爆龟”效果。
选错Offset的后果很严重：Offset太小（负值过大），轮毂可能凸出翼子板，非法且危险；Offset太大，轮毂可能内缩太多，在转向时与悬挂系统的支臂、减震器发生干涉。因此，在购买改装轮毂前，精确计算或验证Offset是必不可少的步骤。
传统的计算方式需要测量轮毂的宽度（通常不是轮胎宽度，是轮毂内缘宽度）和Backspace（轮毂安装面到轮毂内缘的距离），然后进行换算。这个过程对于新手来说不直观，且容易测量失误。一个在线的、交互式的计算器，能够直观地输入测量值、即时得到结果并保存记录，其价值不言而喻。这正是“Offset-Calculator”项目要解决的核心痛点：将专业的、容易出错的线下计算过程，转化为一个直观、可靠、可追溯的数字化工具。
2.2 技术栈选型背后的逻辑
项目采用了相当主流且前沿的React技术栈组合，每一项选择都有其明确的意图：
React 18 + TypeScript：这是构建现代、健壮前端应用的基石。TypeScript的静态类型检查能在开发阶段就捕获大量潜在错误（比如传入非数字字符串进行计算），这对于一个计算工具来说是至关重要的，能确保核心逻辑的可靠性。React 18提供了最新的并发特性（如
useTransition）为未来可能的复杂交互（如大量历史记录渲染）留出了优化空间。Vite：作为构建工具和开发服务器，Vite替代了传统的Create-React-App或Webpack。它的优势在于极快的冷启动和热更新速度，能极大提升开发体验。对于这样一个相对轻量但追求现代开发流程的项目，Vite是比Webpack更敏捷、更快速的选择。
Tailwind CSS v4：项目提到使用了v4，这是一个值得注意的点。Tailwind CSS以其“实用优先”的理念著称，允许开发者通过组合工具类来快速构建UI。v4版本带来了更小的运行时、更智能的优化以及一些新的工具类。选择Tailwind，特别是较新的v4，说明项目追求高效的样式开发流程和现代化的样式输出。其与Neo-Brutalist设计风格的契合度也很高，因为这种风格强调明确的边框、阴影和色彩，用工具类来定义非常方便。
Zustand：状态管理库。相比于Redux的繁琐样板代码，Zustand以其极简的API和概念（一个
create函数创建store）著称。对于这个计算器应用，状态并不复杂（主要是输入值、计算结果、历史记录列表），使用Zustand足以清晰管理，且避免了引入过度设计的复杂度。这是一个“恰到好处”的选择。Neo-Brutalist Design：这不仅是UI风格，更是项目的一大特色。Neo-Brutalism是数字设计中对上世纪中叶建筑领域“粗野主义”的复兴与再诠释。其特点包括：粗重的边框、高对比度的色彩、非平滑的阴影、裸露的骨架感（在UI中体现为明显的组件结构）、以及有时使用的等宽字体。选择这种风格，让这个工具工具在众多Material Design或扁平化设计中脱颖而出，赋予了其强烈的个性、复古未来感以及一种“直给”的功能性气质，非常符合极客和改装爱好者的审美。
注意：技术选型是权衡的结果。例如，没有选择更重量级的状态管理方案（如Redux + Redux Toolkit），也没有选择更全能的CSS-in-JS方案（如Styled-components），都是为了在满足功能需求的前提下，保持项目的轻快和开发的心智负担最小化。这对于一个开源项目吸引贡献者也是有益的。
3. 项目架构与核心模块实现
3.1 项目目录结构深度解读
一个清晰的项目结构是代码可维护性的基础。Offset-Calculator的src/目录组织体现了关注点分离和模块化的思想。
src/ ├── components/ # 所有React组件 │ ├── ui/ # 通用的、可复用的UI基础组件 │ │ ├── BrutalButton.tsx # 具有Neo-Brutalist风格的按钮 │ │ └── BrutalInput.tsx # 风格化输入框 │ └── calculator/ # 计算器功能相关的业务组件 │ ├── CalculatorForm.tsx # 包含输入字段和计算按钮的表单 │ └── HistoryList.tsx # 显示计算历史的列表 ├── store/ │ └── calculatorStore.ts # Zustand状态管理store，集中管理数据状态 ├── types/ │ └── calculator.types.ts # TypeScript类型定义，确保数据安全 └── App.tsx # 应用根组件，组装所有模块这样设计的好处：
ui/目录：将样式与逻辑分离的进阶实践。BrutalButton和BrutalInput封装了Neo-Brutalist的核心视觉样式（如粗边框、阴影、圆角）。任何需要此风格按钮或输入框的地方，都直接使用这些组件，保证了整个应用视觉风格的一致性。未来若要调整风格（比如边框粗细、阴影颜色），只需修改这两个文件即可。calculator/目录：将计算器这个核心功能领域的组件聚集在一起。CalculatorForm专注于数据输入和提交，HistoryList专注于数据展示。逻辑清晰，便于协同开发和测试。- 独立的
store/和types/：将状态管理和类型定义单独抽离，是中型以上React应用的最佳实践。这使得状态流清晰可追溯，类型安全覆盖全局，极大降低了大型应用后期维护的复杂度。
3.2 状态管理：使用Zustand实现数据流
状态管理是任何交互式应用的核心。我们来看calculatorStore.ts的典型实现逻辑：
// store/calculatorStore.ts import { create } from 'zustand'; import { persist } from 'zustand/middleware'; // 用于状态持久化 import { Calculation, CalculatorState } from '../types/calculator.types'; // 定义Store的状态和动作接口 interface CalculatorStore extends CalculatorState { rimWidth: string; backspace: string; offset: number | null; history: Calculation[]; setRimWidth: (value: string) => void; setBackspace: (value: string) => void; calculateOffset: () => void; clearInputs: () => void; addToHistory: (calc: Calculation) => void; clearHistory: () => void; } // 使用`create`创建store，并用`persist`中间件包裹以实现本地存储 export const useCalculatorStore = create<CalculatorStore>()( persist( (set, get) => ({ // 初始状态 rimWidth: '', backspace: '', offset: null, history: [], // 更新轮毂宽度 setRimWidth: (rimWidth) => set({ rimWidth }), // 更新Backspace值 setBackspace: (backspace) => set({ backspace }), // 核心计算函数 calculateOffset: () => { const state = get(); const rimWidthNum = parseFloat(state.rimWidth); const backspaceNum = parseFloat(state.backspace); // 输入验证 if (isNaN(rimWidthNum) || isNaN(backspaceNum) || rimWidthNum <= 0 || backspaceNum <= 0) { // 在实际项目中，这里可以触发一个错误状态或Toast提示 console.error('请输入有效的正数'); return; } // 应用Offset计算公式 // 注意：公式 offset = (rimWidth / 2 - backspace) * -1 // 单位需一致（通常为英寸或毫米） const calculatedOffset = (rimWidthNum / 2 - backspaceNum) * -1; const roundedOffset = Math.round(calculatedOffset * 10) / 10; // 保留一位小数 const newCalculation: Calculation = { id: Date.now(), rimWidth: rimWidthNum, backspace: backspaceNum, offset: roundedOffset, timestamp: new Date().toISOString(), }; // 更新状态：存储结果并添加到历史记录 set({ offset: roundedOffset, history: [newCalculation, ...state.history].slice(0, 50), // 只保留最近50条 }); }, // 清空输入 clearInputs: () => set({ rimWidth: '', backspace: '', offset: null }), // 添加单条记录到历史（calculateOffset中已集成） addToHistory: (calc) => set((state) => ({ history: [calc, ...state.history] })), // 清空全部历史 clearHistory: () => set({ history: [] }), }), { name: 'offset-calculator-storage', // 本地存储的key // 可以选择只持久化部分状态，比如只存history partialize: (state) => ({ history: state.history }), } ) );关键点解析：
- 类型安全：Store完全使用TypeScript定义，
Calculation和CalculatorState类型来自独立的types文件，确保了整个应用中使用数据格式的一致性。 - 计算逻辑集中化：核心的
calculateOffset函数被放在store中。这是一个非常重要的设计决策。它保证了计算逻辑的唯一性，无论哪个组件触发计算，都调用同一个函数，结果一致。同时，输入验证也在这里完成。 - 状态持久化：通过
zustand/middleware/persist，可以轻松地将状态（特别是history）保存到浏览器的localStorage或sessionStorage中。用户关闭页面再打开，计算历史依然存在，提升了用户体验。partialize配置项允许我们选择只持久化必要的部分，避免存储临时输入值等敏感或无用信息。 - 不可变更新：在更新
history时，我们使用了[newCalculation, ...state.history]来创建新数组，这符合React状态更新的不可变原则，能避免潜在的副作用。
3.3 UI组件：实现Neo-Brutalist设计语言
Neo-Brutalist风格需要通过具体的UI组件来落地。以BrutalButton为例：
// components/ui/BrutalButton.tsx import React from 'react'; interface BrutalButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> { variant?: 'primary' | 'secondary'; children: React.ReactNode; } const BrutalButton: React.FC<BrutalButtonProps> = ({ variant = 'primary', children, className = '', ...props }) => { // 基础样式：粗边框、圆角、等宽字体、无背景色过渡 const baseClasses = 'font-mono font-bold px-6 py-3 rounded-lg border-4 transition-all duration-200 active:scale-95 focus:outline-none focus:ring-4'; // 变体样式 const variantClasses = { primary: 'border-gray-900 bg-white text-gray-900 hover:bg-gray-100 focus:ring-gray-300 shadow-[6px_6px_0_0_rgba(0,0,0,0.2)] hover:shadow-[4px_4px_0_0_rgba(0,0,0,0.2)] active:shadow-[2px_2px_0_0_rgba(0,0,0,0.2)]', secondary: 'border-gray-400 bg-gray-800 text-white hover:bg-gray-700 focus:ring-gray-500 shadow-[6px_6px_0_0_rgba(156,163,175,0.3)] hover:shadow-[4px_4px_0_0_rgba(156,163,175,0.3)]', }; return ( <button className={`${baseClasses} ${variantClasses[variant]} ${className}`} {...props} > {children} </button> ); }; export default BrutalButton;设计要点：
- 粗边框：
border-4定义了非常粗的边框，这是Neo-Brutalist的典型特征。 - 强烈阴影：
shadow-[6px_6px_0_0_...]使用Tailwind的任意值功能定义了一个没有模糊度、偏移明显的“硬阴影”，模拟了实物凸起的立体感，而非柔和的弥散阴影。 - 交互状态：
hover:和active:状态改变了阴影大小和背景色，提供了清晰的视觉反馈。active:scale-95在点击时加入轻微的缩放动画，增强了操作感。 - 等宽字体：
font-mono增加了技术感和复古感。
BrutalInput组件也遵循类似原则，拥有粗边框和硬阴影。通过在CalculatorForm中使用这些基础组件，整个应用迅速建立起统一且强烈的视觉风格。
实操心得：在实现Neo-Brutalist风格时，颜色的选择至关重要。高对比度是关键（如黑/白，深灰/亮黄）。但要避免使用过于刺眼的纯色组合，以免影响可读性和长时间使用的舒适度。这个项目使用的深灰边框配白底/黑字，就是一种相对克制且耐看的选择。阴影的“硬度”（模糊度为零）和方向一致性，是营造这种风格氛围的细节关键。
4. 核心功能：Offset计算原理与实现
4.1 Offset计算公式的由来与单位换算
项目给出的公式offset = (altura / 2 - backspace) * -1是计算ET值的核心。我们来拆解一下：
altura：在轮毂术语中，通常指轮毂的宽度（Rim Width），单位通常是英寸（如8J、9.5J）或毫米。这里指的是轮毂两侧法兰盘（Flange）外侧之间的距离。backspace：后距。指轮毂的安装面（Mounting Surface）到轮毂内侧法兰盘外缘的垂直距离。altura / 2：得到轮毂的理论中心线位置。(altura / 2 - backspace)：理论中心线到安装面的距离。如果安装面在中心线内侧，此值为正；在外侧，则为负。* -1：这是为了符合行业标准ET值的定义。ET值的正负定义与上述计算结果正好相反。所以需要乘以-1来转换。- 最终结果 > 0：正ET，安装面在中心线外侧。
- 最终结果 = 0：零ET，安装面与中心线重合。
- 最终结果 < 0：负ET，安装面在中心线内侧。
单位陷阱与处理： 这是实际使用中最容易出错的地方。轮毂宽度（altura）常用英寸表示，而Backspace常用毫米或英寸表示。公式计算的前提是两者单位必须一致！
- 如果宽度是8英寸，Backspace是120毫米，直接计算毫无意义。
- 标准做法是全部转换为毫米进行计算。1英寸 = 25.4毫米。
- 因此，一个健壮的计算器应该允许用户选择输入单位，并在内部进行统一转换。
改进后的计算逻辑：
interface CalculationInput { rimWidthValue: number; rimWidthUnit: 'mm' | 'inch'; backspaceValue: number; backspaceUnit: 'mm' | 'inch'; } function calculateOffsetInMM(input: CalculationInput): number { // 统一转换为毫米 const rimWidthMM = input.rimWidthUnit === 'inch' ? input.rimWidthValue * 25.4 : input.rimWidthValue; const backspaceMM = input.backspaceUnit === 'inch' ? input.backspaceValue * 25.4 : input.backspaceValue; // 应用公式 const offsetMM = (rimWidthMM / 2 - backspaceMM) * -1; return Math.round(offsetMM * 10) / 10; // 返回毫米值，保留一位小数 }在UI上，可以为每个输入框旁边增加一个单位选择下拉菜单（毫米/英寸），并在结果显示时明确标出单位（如“ET: +35mm”）。
4.2 测量指南：如何获取准确的输入值
计算器再准，输入数据错了也是白搭。这里给出一份详细的测量指南：
测量轮毂宽度 (altura/ Rim Width)：
- 找到轮毂的“J值”标记。通常刻在轮毂背面，如“18x8.5J”。这里的8.5就是宽度（英寸）。这是最准确的方法。
- 如果没有标记，则需要用卡尺测量。测量的是轮毂两侧法兰盘（安装轮胎的凸起边缘）的内侧之间的距离。注意，不是轮毂整体的宽度，也不是轮胎的宽度。
测量Backspace：
- 将轮毂正面朝下平放在地面。
- 找一根直尺或激光测距仪，垂直立于轮毂安装面（与车轴接触的平整面）。
- 测量从安装面到轮毂内侧法兰盘外缘的垂直距离。这是最关键的步骤，“内侧”指朝向车辆中心的那一侧。
- 为确保准确，应在轮毂上对称测量多个点取平均值，因为旧轮毂可能有轻微变形。
重要提示：对于有巨大负Offset的深唇轮毂，Backspace值可能很小甚至为负（安装面在轮毂内侧法兰盘之外），测量时要格外小心。建议在购买二手轮毂或定制轮毂时，要求卖家提供准确的ET值或Backspace值。
4.3 计算器表单组件的实现细节
CalculatorForm组件是用户交互的核心。它需要：
- 绑定到Zustand store中的
rimWidth和backspace状态。 - 提供输入框让用户修改这些值。
- 在用户点击“计算”按钮时，触发store中的
calculateOffset动作。 - 实时显示计算结果或错误信息。
// components/calculator/CalculatorForm.tsx (简化示例) import React from 'react'; import BrutalInput from '../ui/BrutalInput'; import BrutalButton from '../ui/BrutalButton'; import { useCalculatorStore } from '../../store/calculatorStore'; const CalculatorForm: React.FC = () => { const { rimWidth, backspace, offset, setRimWidth, setBackspace, calculateOffset, clearInputs } = useCalculatorStore(); const handleCalculate = () => { calculateOffset(); }; const handleClear = () => { clearInputs(); }; return ( <div className="p-8 border-4 border-gray-800 rounded-2xl bg-white shadow-[10px_10px_0_0_rgba(0,0,0,0.1)]"> <h2 className="text-2xl font-mono font-bold mb-6 text-gray-900">轮毂Offset计算器</h2> <div className="space-y-6"> <div> <label htmlFor="rimWidth" className="block text-sm font-medium text-gray-700 mb-2 font-mono"> 轮毂宽度 (单位：毫米) </label> <BrutalInput id="rimWidth" type="number" placeholder="例如：225 (或 8.85 英寸)" value={rimWidth} onChange={(e) => setRimWidth(e.target.value)} step="0.1" min="0" /> <p className="mt-1 text-sm text-gray-500">请测量轮毂内侧宽度（法兰盘内侧间距）。</p> </div> <div> <label htmlFor="backspace" className="block text-sm font-medium text-gray-700 mb-2 font-mono"> 后距 Backspace (单位：毫米) </label> <BrutalInput id="backspace" type="number" placeholder="例如：150" value={backspace} onChange={(e) => setBackspace(e.target.value)} step="0.1" min="0" /> <p className="mt-1 text-sm text-gray-500">安装面到轮毂内侧法兰盘外缘的距离。</p> </div> <div className="flex flex-col sm:flex-row gap-4 pt-4"> <BrutalButton variant="primary" onClick={handleCalculate} className="flex-1"> 计算 Offset </BrutalButton> <BrutalButton variant="secondary" onClick={handleClear} className="flex-1"> 清空输入 </BrutalButton> </div> {/* 结果显示区域 */} {offset !== null && ( <div className="mt-8 p-6 border-4 border-gray-900 rounded-xl bg-gray-50"> <h3 className="text-xl font-mono font-bold mb-2 text-gray-900">计算结果</h3> <div className="text-4xl font-mono font-black text-center my-4"> ET: <span className={offset >= 0 ? 'text-blue-600' : 'text-red-600'}>{offset > 0 ? '+' : ''}{offset.toFixed(1)}</span> mm </div> <p className="text-sm text-gray-600 text-center"> {offset === 0 ? '零Offset，安装面与中心线重合。' : offset > 0 ? `正Offset (ET+${offset.toFixed(1)})，轮毂安装面在中心线外侧。` : `负Offset (ET${offset.toFixed(1)})，轮毂安装面在中心线内侧，轮毂更外凸。`} </p> </div> )} </div> </div> ); }; export default CalculatorForm;这个组件清晰地组织了输入、按钮和结果展示区域，并集成了所有的交互逻辑。使用flex-1类让按钮在移动端堆叠，在大屏上并排且等宽，实现了响应式布局。
5. 数据持久化与历史记录功能
5.1 利用Zustand Persist实现本地存储
如前所述，Zustand的persist中间件让状态持久化变得极其简单。配置中的name指定了存储在localStorage中的键名。partialize函数允许我们选择只持久化history数组，而忽略临时性的输入值（rimWidth,backspace）和当前计算结果（offset）。这样做是合理的，因为用户通常希望历史记录在下次访问时依然存在，但不需要恢复上次未完成的输入。
persist( (set, get) => ({ /* ... store logic ... */ }), { name: 'offset-calculator-storage', partialize: (state) => ({ history: state.history }), } )5.2 历史记录列表组件的设计与交互
HistoryList组件负责展示和操作历史记录。它需要：
- 从store中读取
history数组。 - 以列表形式展示每条记录的关键信息（宽度、Backspace、Offset、时间）。
- 提供删除单条记录或清空全部记录的交互。
// components/calculator/HistoryList.tsx import React from 'react'; import { useCalculatorStore } from '../../store/calculatorStore'; import { Calculation } from '../../types/calculator.types'; import { Trash2, XCircle } from 'lucide-react'; // 使用图标库增强UI const HistoryList: React.FC = () => { const { history, clearHistory } = useCalculatorStore(); // 从store中获取删除单条记录的函数（需要在store中实现） // 假设我们为store添加了`removeFromHistory`动作 const removeFromHistory = useCalculatorStore((state) => state.removeFromHistory); if (history.length === 0) { return ( <div className="p-8 text-center border-4 border-gray-300 rounded-2xl bg-gray-50"> <p className="text-gray-500 font-mono">暂无计算历史。开始计算吧！</p> </div> ); } const handleDeleteOne = (id: number) => { if (window.confirm('确定要删除这条记录吗？')) { removeFromHistory(id); } }; const handleDeleteAll = () => { if (window.confirm('确定要清空所有历史记录吗？此操作不可撤销。')) { clearHistory(); } }; return ( <div className="p-6 border-4 border-gray-800 rounded-2xl bg-white shadow-[10px_10px_0_0_rgba(0,0,0,0.1)]"> <div className="flex justify-between items-center mb-6"> <h2 className="text-2xl font-mono font-bold text-gray-900">计算历史</h2> <button onClick={handleDeleteAll} className="flex items-center gap-2 px-4 py-2 border-2 border-red-500 text-red-500 rounded-lg font-mono font-bold hover:bg-red-50 transition-colors" aria-label="清空历史" > <Trash2 size={18} /> 清空全部 </button> </div> <ul className="space-y-4"> {history.map((item: Calculation) => ( <li key={item.id} className="flex flex-col sm:flex-row sm:items-center justify-between p-4 border-2 border-gray-300 rounded-lg hover:border-gray-400 hover:bg-gray-50 transition-all group" > <div className="flex-1"> <div className="flex flex-wrap items-baseline gap-2 mb-1"> <span className="font-mono text-lg font-bold"> 宽度: <span className="text-gray-900">{item.rimWidth.toFixed(1)}mm</span> </span> <span className="text-gray-400">|</span> <span className="font-mono text-lg font-bold"> Backspace: <span className="text-gray-900">{item.backspace.toFixed(1)}mm</span> </span> </div> <div className="flex items-baseline gap-2"> <span className="font-mono text-2xl font-black"> ET: <span className={item.offset >= 0 ? 'text-blue-600' : 'text-red-600'}>{item.offset > 0 ? '+' : ''}{item.offset.toFixed(1)}mm</span> </span> <span className="text-sm text-gray-500 font-mono"> {new Date(item.timestamp).toLocaleString('zh-CN')} </span> </div> </div> <button onClick={() => handleDeleteOne(item.id)} className="mt-2 sm:mt-0 sm:ml-4 p-2 text-gray-400 hover:text-red-500 hover:bg-red-50 rounded transition-colors opacity-0 group-hover:opacity-100 focus:opacity-100" aria-label="删除此记录" > <XCircle size={20} /> </button> </li> ))} </ul> <p className="mt-4 text-sm text-gray-500 text-center font-mono"> 共 {history.length} 条记录。仅保留最近50条。 </p> </div> ); }; export default HistoryList;交互细节：
- 悬停显示删除按钮：通过
group和group-hover:opacity-100实现了鼠标悬停在列表项上时才显示删除按钮，保持了界面整洁。 - 确认对话框：在执行删除操作前弹出浏览器原生的
confirm对话框，防止误操作。在生产级应用中，可能会使用更美观的自定义模态框。 - 响应式布局：使用
flex-col sm:flex-row让列表项在移动端垂直排列，在桌面端水平排列以更好地利用空间。 - 信息层次：使用字体大小、粗细和颜色来区分数据的主次（如Offset值最大最醒目，时间戳较小且颜色较浅）。
6. 项目构建、部署与扩展思考
6.1 开发与构建流程
项目使用Vite，因此开发命令非常标准：
npm install # 安装依赖 npm run dev # 启动开发服务器，通常访问 http://localhost:5173 npm run build # 构建生产版本，输出到 `dist` 目录 npm run preview # 本地预览构建后的产物vite.config.ts可能包含一些针对该项目的优化配置，例如：
import { defineConfig } from 'vite'; import react from '@vitejs/plugin-react'; export default defineConfig({ plugins: [react()], // 为生产构建配置公共路径（如果部署在子路径下） // base: '/your-subpath/', build: { // 生成独立的CSS文件，有利于缓存 cssCodeSplit: true, // 配置构建输出目录和文件名哈希 rollupOptions: { output: { assetFileNames: 'assets/[name]-[hash][extname]', chunkFileNames: 'assets/[name]-[hash].js', entryFileNames: 'assets/[name]-[hash].js', }, }, }, });6.2 部署到静态托管平台
由于这是一个纯前端的静态SPA（单页应用），部署极其简单。构建生成的dist文件夹可以直接托管在任何静态网站服务上。
主流选择：
- Vercel / Netlify：最推荐。与GitHub等代码仓库无缝集成，支持自动部署。只需连接仓库，它们会自动检测到Vite项目并配置好构建和部署命令。通常提供免费的二级域名和HTTPS。
- GitHub Pages：免费，适合开源项目。需要在项目中配置正确的
base路径，并可能通过GitHub Actions自动化部署流程。 - Cloudflare Pages：同样提供免费的自动化部署、全球CDN和HTTPS，性能优秀。
部署后，用户就可以通过一个公开的URL访问这个轮毂Offset计算器了。
6.3 功能扩展与未来方向
这个计算器已经解决了核心问题，但仍有很大的扩展空间，使其对改装爱好者更具吸引力：
- 轮毂数据库/预设：允许用户从下拉菜单中选择常见车型或轮毂型号，自动填充原厂轮毂的宽度、ET值等信息，方便用户对比改装数据。
- 视觉化模拟器：这是一个“杀手级”功能。根据计算出的ET值，结合用户输入的翼子板宽度等参数，在侧视图中模拟轮毂与翼子板的相对位置，用图形直观展示是“齐边”、“内凹”还是“外凸”。
- 单位智能转换与识别：如前所述，增强单位处理。甚至可以尝试自动识别输入的单位（例如，用户输入“8.5”，大概率是英寸；输入“215”，大概率是毫米）。
- 轮胎尺寸计算器：增加轮胎尺寸计算功能，根据轮毂宽度推荐合适的轮胎宽度、扁平比，并计算轮胎整体直径，确保车速表准确且不影响车辆动态。
- 分享功能：允许用户将某次计算结果（包括输入参数和结果）生成一个短链接或图片，方便在论坛或社交媒体上分享讨论。
- 多语言支持：项目初始是葡萄牙语，可以很容易地通过i18n库（如
react-i18next）添加中文、英文等多语言支持，使其更具国际性。
踩坑记录：在早期版本中，我曾尝试将计算逻辑直接写在组件里。这导致了一个问题：当需要在多个地方（如表单提交、历史记录回填计算）执行相同计算时，逻辑重复且难以维护。后来将逻辑全部迁移到Zustand store中，形成了“单一数据源”和“单一计算逻辑”，状态管理立刻清晰了许多。这也印证了状态逻辑与UI逻辑分离的重要性。
7. 常见问题与排查实录
在实际开发和使用这类工具时，会遇到一些典型问题。这里记录一下我的排查过程和解决方案。
7.1 计算精度问题与浮点数处理
问题：JavaScript的浮点数计算存在精度问题，例如0.1 + 0.2并不等于0.3。在Offset计算中，即使输入整数，经过/2和* -1运算后，也可能产生类似35.00000000000006的结果。
解决方案：在显示和存储前，必须进行舍入。
// 四舍五入保留一位小数 const roundedOffset = Math.round(calculatedOffset * 10) / 10; // 或者使用 toFixed，但注意它返回字符串 const offsetString = calculatedOffset.toFixed(1); // "35.0"在store中存储时，建议存储舍入后的数字（roundedOffset），而不是字符串，以便后续进行数值比较或计算。
7.2 输入验证与用户体验
问题：用户可能在输入框中输入非数字、负数或留空，直接进行计算会导致NaN或错误结果。
解决方案：在store的calculateOffset函数中加强验证。
calculateOffset: () => { const state = get(); const rimWidthNum = parseFloat(state.rimWidth); const backspaceNum = parseFloat(state.backspace); // 1. 检查是否为空或非数字 if (state.rimWidth.trim() === '' || state.backspace.trim() === '') { // 可以设置一个错误状态，在UI上显示“请输入有效值” set({ error: '请输入宽度和Backspace值' }); return; } if (isNaN(rimWidthNum) || isNaN(backspaceNum)) { set({ error: '请输入有效的数字' }); return; } // 2. 检查是否为合理的正数（宽度和Backspace理论上应为正） if (rimWidthNum <= 0 || backspaceNum <= 0) { set({ error: '宽度和Backspace值必须大于0' }); return; } // 3. 逻辑检查：Backspace理论上不应大于轮毂宽度的一半（否则ET会非常负，不现实） if (backspaceNum > rimWidthNum) { set({ error: 'Backspace值通常不应大于轮毂宽度，请检查测量' }); return; } // 清除错误，执行计算 set({ error: null }); // ... 后续计算逻辑 }在UI组件中，需要根据store中的error状态来显示相应的错误提示信息。
7.3 移动端适配与触摸交互
问题：Neo-Brutalist的粗边框和按钮在移动端小屏幕上可能显得过于“笨重”，影响可用性。
解决方案：利用Tailwind的响应式工具类进行微调。
// 在 BrutalButton 组件中调整 const baseClasses = 'font-mono font-bold px-4 py-3 rounded-lg border-4 transition-all duration-200 active:scale-95 focus:outline-none focus:ring-4 md:px-6'; // 在 CalculatorForm 容器上调整 <div className="p-4 border-4 border-gray-800 rounded-2xl bg-white shadow-[6px_6px_0_0_rgba(0,0,0,0.1)] md:p-8 md:shadow-[10px_10px_0_0_rgba(0,0,0,0.1)]">- 在移动端（默认）使用较小的内边距（
p-4）和阴影（shadow-[6px_6px_...]）。 - 在中等屏幕及以上（
md:）使用更大的内边距和阴影，以保持桌面端的视觉冲击力。 - 确保所有交互元素（按钮、输入框）的触摸目标尺寸足够大（至少44x44像素），符合无障碍设计标准。
7.4 状态持久化版本冲突
问题：如果未来更新了store的结构（例如新增了一个状态字段），已保存在用户浏览器localStorage中的旧版本数据可能导致新版本应用出错。
解决方案：Zustand Persist提供了version选项和migrate函数来处理状态迁移。
persist( (set, get) => ({ /* ... new store logic ... */ }), { name: 'offset-calculator-storage', version: 2, // 每次store结构有重大变更时，递增版本号 migrate: (persistedState, version) => { // 当前版本是2，如果从版本1升级过来 if (version === 1) { // 假设旧state结构是 { history: [...], someOldField: ... } // 我们可以将其转换为新结构，或丢弃不兼容的字段 return { history: persistedState.history, // 新字段赋予默认值 rimWidth: '', backspace: '', offset: null, }; } return persistedState; // 如果版本相同或更高，直接返回 }, } )7.5 性能优化：虚拟化长列表
问题：如果用户疯狂计算，历史记录可能非常多（虽然我们限制了50条）。渲染一个很长的列表在低性能设备上可能导致滚动卡顿。
解决方案：当列表项超过一定数量（比如20条）时，考虑使用虚拟滚动库，如react-virtualized或@tanstack/react-virtual。它们只渲染可视区域内的列表项，极大提升长列表性能。
// 使用 @tanstack/react-virtual 的简化示例 import { useVirtualizer } from '@tanstack/react-virtual'; function VirtualizedHistoryList({ items }) { const parentRef = React.useRef(); const rowVirtualizer = useVirtualizer({ count: items.length, getScrollElement: () => parentRef.current, estimateSize: () => 80, // 每行大约高度 }); return ( <div ref={parentRef} style={{ height: '400px', overflow: 'auto' }}> <div style={{ height: `${rowVirtualizer.getTotalSize()}px`, position: 'relative' }}> {rowVirtualizer.getVirtualItems().map((virtualRow) => { const item = items[virtualRow.index]; return ( <div key={item.id} style={{ position: 'absolute', top: 0, left: 0, width: '100%', height: `${virtualRow.size}px`, transform: `translateY(${virtualRow.start}px)`, }} > {/* 渲染单个历史记录项 */} <HistoryItem item={item} /> </div> ); })} </div> </div> ); }对于这个计算器，50条记录通常不需要虚拟化，但了解这种技术对于构建更复杂的应用是有益的。
