告别代码报错，陈列馆保姆级教程带你从零搭建
刚接手一个项目，把网上扒来的“陈列馆”展示模块代码复制进来，直接报错 Module not found。是不是你也遇到过这种糟心事儿？明明逻辑看着对，运行起来就是一堆红字，调试半天找不到北。别慌，今天这篇保姆级教程，不玩虚的，直接带你从零搭建一个能跑、能看、能用的数字陈列馆核心模块。咱们不整那些高大上的概念，就盯着“怎么让代码跑通”和“怎么避坑”来。
项目目标：我们要解决什么
很多初学者或者刚入行的开发者，在做一个“数字文化陈列馆”或者“产品3D展示页”时，容易陷入两个误区。一是觉得必须用 WebAssembly 或者 Three.js 这种重型库，结果环境配置就卡住两天；二是复制代码不看依赖，直接 npm install 后运行，发现一堆版本冲突。
我们要做的这个“陈列馆”模块，目标很明确：基于 React 和 TypeScript，实现一个轻量级的图片/模型轮播展示区。它不需要复杂的 3D 引擎，但要求交互流畅、加载快速、兼容性好。更重要的是，我要把其中容易踩坑的几个点——比如图片懒加载的时机、浏览器兼容性处理、以及状态管理的同步问题——全部讲透。
对于培训机构学员来说，掌握这个模块，意味着你理解了前端组件化开发的核心逻辑：如何拆分组件、如何管理异步数据、如何处理用户交互。这比单纯背 API 有用得多。
目录结构：清晰即正义
在动手写代码前，先把目录结构理清楚。混乱的结构是后期维护噩梦的根源。建议采用以下结构，简单但规范：
src/
├── components/
│ ├── ExhibitHall/
│ │ ├── ExhibitHall.tsx # 主组件，负责布局
│ │ ├── ItemCard.tsx # 单个展品卡片
│ │ └── useExhibitData.ts # 自定义 Hook，负责数据获取
│ └── common/
│ └── Spinner.tsx # 加载状态组件
├── types/
│ └── exhibit.d.ts # 类型定义
├── utils/
│ └── imageLoader.ts # 图片预加载工具
└── App.tsx
关键点说明：
useExhibitData.ts单独抽离：数据获取逻辑与 UI 分离，方便测试和复用。types/exhibit.d.ts：TypeScript 项目中，类型定义一定要独立。不要偷懒写在组件文件里，否则多人协作时极易冲突。utils/imageLoader.ts：处理图片加载状态，避免“白屏闪烁”。
核心代码实现：逐行拆解
1. 类型定义与数据模拟
首先，我们定义好数据的结构。在真实项目中，这通常来自后端 API。
// src/types/exhibit.d.ts
export interface ExhibitItem {id: number;title: string;description: string;imageUrl: string;modelUrl?: string; // 可选的3D模型路径status: 'available' | 'maintenance';
}
在 useExhibitData.ts 中，我们模拟一个异步请求过程。注意，这里使用了 useEffect 和 useState，这是 React 数据获取的标准范式。
// src/components/ExhibitHall/useExhibitData.ts
import { useState, useEffect } from 'react';
import { ExhibitItem } from '../../types/exhibit';export function useExhibitData() {const [data, setData] = useState<ExhibitItem[]>([]);const [loading, setLoading] = useState<boolean>(true);const [error, setError] = useState<string | null>(null);useEffect(() => {const fetchExhibits = async () => {try {setLoading(true);// 模拟网络请求延迟await new Promise(resolve => setTimeout(resolve, 1500));// 模拟数据，实际项目中替换为 axios.get('/api/exhibits')const mockData: ExhibitItem[] = [{id: 1,title: '青铜器·司母戊鼎',description: '商代晚期青铜礼器',imageUrl: '/images/ding.jpg',status: 'available'},{id: 2,title: '书画·兰亭集序',description: '王羲之代表作',imageUrl: '/images/lanting.jpg',status: 'maintenance'}];setData(mockData);} catch (err) {setError('数据加载失败，请检查网络连接');} finally {setLoading(false);}};fetchExhibits();}, []); // 依赖数组为空，仅初始化时执行return { data, loading, error };
}
避坑指南：
很多新手会在 useEffect 里直接写同步代码，或者忘记在 catch 块中设置错误状态。这会导致一旦接口超时，页面没有任何反馈，用户以为卡死了。务必加上 error 状态处理。
2. 主组件与交互逻辑
接下来是核心 UI 部分。ExhibitHall.tsx 负责整体布局，并调用 ItemCard。
// src/components/ExhibitHall/ExhibitHall.tsx
import React from 'react';
import { useExhibitData } from './useExhibitData';
import { ItemCard } from './ItemCard';
import { Spinner } from '../common/Spinner';export const ExhibitHall: React.FC = () => {const { data, loading, error } = useExhibitData();if (loading) {return <Spinner message="正在加载展品..." />;}if (error) {return <div className="error-box">{error}</div>;}return (<div className="exhibit-hall-container"><h2>数字陈列馆</h2><div className="exhibit-grid">{data.map((item) => (<ItemCard key={item.id} item={item} />))}</div></div>);
};
这里有一个容易忽略的细节：key 属性。在 map 渲染列表时，必须使用唯一且稳定的 key（如 item.id）。如果用 index 作为 key，当数据排序或筛选变化时，React 的 diff 算法会失效，导致状态错乱。这是一个非常隐蔽但高频的 Bug 来源。
3. 单品卡片与图片懒加载
ItemCard.tsx 是用户直接看到的单元。为了性能，我们实现了简单的图片懒加载。
// src/components/ExhibitHall/ItemCard.tsx
import React, { useState } from 'react';
import { ExhibitItem } from '../../types/exhibit';interface Props {item: ExhibitItem;
}export const ItemCard: React.FC<Props> = ({ item }) => {const [imageLoaded, setImageLoaded] = useState(false);const handleImageLoad = () => {setImageLoaded(true);};return (<div className="item-card"><div className="image-wrapper">{!imageLoaded && <div className="placeholder">加载中...</div>}<imgsrc={item.imageUrl}alt={item.title}className={imageLoaded ? 'loaded' : 'loading'}onLoad={handleImageLoad}// 关键：设置 width 和 height 防止布局抖动width={300}height={300}/></div><div className="info"><h3>{item.title}</h3><p>{item.description}</p>{item.status === 'maintenance' && (<span className="tag">维护中</span>)}</div></div>);
};
为什么要在 img 标签上写死 width 和 height？
这是很多教程不会强调的细节。如果不指定尺寸，浏览器在图片加载前不知道它占多大地方，会导致页面内容随着图片加载完成而“跳动”（Layout Shift）。这在用户体验上是灾难，也会严重影响 SEO 评分。
运行与测试：验证你的成果
代码写完了，别急着点运行。先进行静态检查。
- TypeScript 检查：运行
npm run tsc --noEmit。如果有任何类型错误，必须修复。类型系统是 TypeScript 的核心价值，不能因为“能跑”就忽略类型警告。 - 本地运行：
npm run dev。打开浏览器开发者工具（F12），切换到 Network 面板，刷新页面。观察/images/ding.jpg等请求的状态。 - 交互测试：
- 模拟断网：在 Network 面板选择 "Offline"，刷新页面，看是否出现错误提示。
- 快速切换：如果有切换展品的功能，快速点击，看是否有内存泄漏或状态错乱（可通过 Chrome 的 Memory 面板初步判断）。
常见故障排查：
- 图片裂开：检查
src路径是否正确。如果是相对路径，确保部署时的base配置正确。 - 样式丢失：检查 CSS 模块化的文件名是否与 import 一致。
- 控制台报错
Cannot read property of undefined：90% 的情况是因为数据还没加载完就访问了属性。务必确保if (!data) return null;这样的防御性代码。
优化扩展：从“能跑”到“好用”
基础功能跑通后，我们来看几个提升项目质量的关键点。这也是区分初级和中级开发者的分水岭。
1. 图片优化策略
对于“陈列馆”这种图片密集型项目，图片加载速度决定生死。
- WebP 格式：如果后端支持，优先请求 WebP 格式，兼容性不好时回退到 JPEG/PNG。
- CDN 加速：将图片资源上传至 CDN。在掘金技术社区的很多高性能案例中，图片优化往往是提速的第一功臣。
- 占位图：在图片加载前，显示一张极小尺寸的模糊图（BlurHash 或 Base64 缩略图），避免白屏。
2. 错误边界（Error Boundary）
React 组件的错误不应该导致整个应用崩溃。我们需要一个 Error Boundary。
// src/components/common/ErrorBoundary.tsx
import React from 'react';interface State {hasError: boolean;
}export class ErrorBoundary extends React.Component<React.PropsWithChildren, State> {constructor(props: any) {super(props);this.state = { hasError: false };}static getDerivedStateFromError() {// 更新 state so the next render will show the fallback UI.return { hasError: true };}componentDidCatch(error: any, errorInfo: any) {// Log the error to an error reporting serviceconsole.error('Uncaught error:', error, errorInfo);}render() {if (this.state.hasError) {return <h1>出了点问题，请稍后重试。</h1>;}return this.props.children;}
}
在 App.tsx 中，用 ErrorBoundary 包裹 <ExhibitHall />。这样即使陈列馆模块崩溃，导航栏、页脚等其他部分依然可用。
3. 无障碍访问（A11y）
不要忽略这一点，它是专业性的体现。
- 确保所有
img都有alt属性，且内容有意义。 - 使用语义化 HTML 标签，如
<article>,<section>,<aside>。 - 确保键盘操作可行，焦点顺序合理。
小结与互动
回顾一下，我们从零搭建了一个简单的数字陈列馆模块。核心不在于代码多复杂，而在于规范的结构、严谨的类型、防御性的编程以及对性能细节的关注。
很多同学在复制代码时，只关注了“怎么实现功能”，忽略了“代码为什么这么写”。比如，为什么要有 key？为什么图片要设尺寸？为什么要有 Error Boundary？这些“为什么”，才是你面试时能拿高分的关键。
这个知识点你面试被问过吗？留言说说，你遇到过最离谱的前端 Bug 是什么？或者是你在实际项目中是如何处理图片加载失败的？期待在评论区看到大家的真实经验。
