当前位置：首页 > news >正文

Next.js实战：构建高性能疫情信息平台的技术架构与工程实践

news 2026/5/8 19:54:58

1. 项目概述：一个由社区驱动的疫情信息枢纽

如果你在2021年那段时间关注过印尼的疫情，可能听说过或者用过Warga Bantu Warga（居民互助居民）这个网站。它不是一个官方项目，而是一个完全由志愿者驱动的开源社区倡议。当时，印尼的医疗系统面临巨大压力，床位、氧气瓶、药品等信息极度分散，很多求助信息在社交媒体和Google Docs上流转，但查找和验证非常困难。这个项目的核心目标，就是把这些散落在各处、公开可访问的Google Docs表格，转化成一个移动端友好、性能优异、信息实时的网站，让急需帮助的人能快速找到救命资源。

我作为早期参与者之一，深度经历了从技术选型、架构搭建到持续迭代的全过程。这不仅仅是一个技术项目，更是一次在紧急状态下，如何用开源协作和现代Web技术解决实际社会问题的生动实践。项目采用了Next.js、React、Tailwind CSS这套技术栈，并严格遵循性能、可访问性、信息实时性三大核心原则。整个代码库托管在GitHub上，吸引了超过50位贡献者，成为了一个真正意义上的社区共建项目。

今天，我想抛开项目本身的社会意义，从一个资深开发者的角度，深入复盘这个项目的技术架构、工程实践和那些在高压、快速迭代下踩过的坑。无论你是想学习如何构建一个高性能的、以内容为中心的现代Web应用，还是想了解大型开源社区项目如何协作与管理，亦或是单纯对Next.js的深度应用感兴趣，我相信这里的经验都能给你带来启发。

2. 核心设计原则与工程哲学

在项目启动之初，我们就意识到，这不仅仅是一个“把表格变成网页”的简单任务。在印尼，用户设备的性能和网络条件差异巨大。我们必须确保一个用着老旧安卓手机、在信号不稳定的乡村用户，也能流畅地访问网站。同时，信息的准确性就是生命线，过时的床位信息可能意味着生命的代价。因此，我们确立了一套非常清晰且严格的设计原则，这直接决定了后续所有的技术决策。

2.1 核心原则：什么必须做，什么必须避免

我们的原则被明确地分为“追求”和“反对”两部分，这比泛泛而谈的“要好”更有指导性。

我们追求（✅）：

性能为王：网站必须高性能。我们以Google的Core Web Vitals作为核心衡量标准。这意味着我们需要关注LCP（最大内容绘制）、FID（首次输入延迟）和CLS（累积布局偏移）。尤其是在移动网络下，首屏加载速度和交互响应速度至关重要。
可访问性：网站必须能被所有人使用，包括残障人士。这意味着正确的HTML语义、足够的颜色对比度、完整的键盘导航支持和屏幕阅读器兼容。这不仅关乎道德，也关乎信息的可达性——在危机中，任何人都可能是求助者。
信息实时性：网站内容必须与源头Google Docs保持同步。我们允许一定的延迟（例如为了做静态生成优化），但这个延迟必须被严格控制在一小时以内。过时的信息比没有信息更危险。
迭代式、渐进式变更：我们承认软件开发是复杂的认知工作。因此，我们崇尚简化。通过缩小范围、推迟低价值功能，我们可以更快地将高价值部分交付给用户。每次提交都应该小而可验证。

我们反对（❌）：

有损性能的“化妆品”：任何仅仅为了“好看”而损害性能或导致信息更新延迟的设计，都是不可接受的。UI设计必须服务于功能和性能。
昂贵的客户端功能：对任何需要引入额外客户端JavaScript库的功能，我们都持极度审慎的态度。必须严格评估其收益与带来的性能损耗。一个典型的例子是我们对Google Analytics的引入进行了长达数周的讨论和性能测试，最终以最优化、对性能影响最小的方式集成。
未经测量的“优化”：任何对网站的改动，无论是功能还是“优化”，都必须持续监控其对Core Web Vitals的影响。如果某项改动导致指标恶化，我们必须回滚并寻找不损害性能的实现方案。

2.2 技术选型背后的“为什么”

基于以上原则，我们的技术栈选择变得顺理成章：

Next.js：这是基石。它提供了服务端渲染和静态生成能力，这对实现“性能”和“实时性”的平衡至关重要。我们可以为不常变动的页面（如“关于我们”）做静态生成，对数据频繁变化的页面（如各省市医疗资源列表）采用增量静态再生成或服务端渲染，确保用户看到的内容既快又新。其内置的路由、API路由和图像优化组件，极大地提升了开发效率和最终性能。
React：作为UI库，其组件化模型非常适合构建这种内容结构复杂但交互相对标准的网站。结合Next.js，我们能轻松实现部分 hydration，进一步优化首屏体验。
Tailwind CSS：选择它纯粹是为了开发速度和最终产物体积。在需要快速迭代、且UI组件众多的情况下，实用优先的CSS框架避免了编写大量自定义CSS，减少了CSS bundle的大小，并且通过PurgeCSS（现在叫@tailwindcss/jit）可以极致地剔除未使用的样式，这对性能是直接利好。
数据源：Google Sheets API：这是项目的关键创新点，也是最大的挑战。为什么不用传统的CMS（如WordPress）或自建后台？因为我们的内容编辑志愿者遍布各地，且很多是非技术人员。Google Docs是他们最熟悉、协作门槛最低的工具。我们的技术挑战就变成了：如何可靠、高效、自动化地将Google Docs中的数据“同步”到Next.js应用中，并转化为结构化的、可查询的网页内容。

实操心得：在项目初期明确并坚守这些原则，为后续所有技术争论提供了“宪法”般的裁决依据。当有人提议添加一个华丽的动画库时，我们可以直接问：“这会对LCP或CLS产生多大影响？我们有数据证明它值得吗？”这种以性能和用户价值为导向的工程文化，是项目成功的关键。

3. 架构深度解析：数据流与渲染策略

理解了“做什么”和“不做什么”之后，我们来看看具体“怎么做”。整个系统的核心架构可以概括为：从Google Docs获取数据，经过处理和验证，最终通过Next.js以最优化的方式呈现给用户。

3.1 数据同步管道：从Google Sheets到静态页面

这是整个系统的生命线。我们构建了一个自动化的数据管道，其流程如下：

数据获取：我们编写了Node.js脚本（项目中的yarn fetch-wbw命令），定期调用Google Sheets API，读取指定的公开电子表格。每个省份、每种资源（病床、氧气、药物）可能对应不同的Sheet。
数据清洗与转换：原始表格数据往往包含不一致的格式、多余的空格、非标准化的选项。脚本需要执行清洗工作，比如将“Tersedia”（可用）、“Ada”（有）统一为“Available”，将电话号码格式标准化，并过滤掉明显错误或已过期的条目。
结构化与序列化：清洗后的数据被转换为更利于前端消费的JSON结构。我们会按省份、城市、资源类型进行嵌套组织，并可能添加一些衍生字段，如“最后更新时间戳”。
写入本地/触发构建：生成的JSON文件被写入到代码库的特定目录（如/public或/data）。更高级的做法是，这个数据获取过程可以作为一个GitHub Action，在数据更新时自动提交更改并触发Netlify/Vercel的重新部署，实现“数据驱动部署”。

// 这是一个简化的数据获取脚本概念示例 const { google } = require('googleapis'); const fs = require('fs'); async function fetchAndTransformSheetData() { // 1. 认证并初始化Google Sheets API客户端 const auth = new google.auth.GoogleAuth({...}); const sheets = google.sheets({ version: 'v4', auth }); // 2. 获取指定Sheet的数据 const response = await sheets.spreadsheets.values.get({ spreadsheetId: '你的表格ID', range: '床位信息!A2:F1000', // 指定范围 }); const rows = response.data.values; // 3. 数据清洗与转换 const transformedData = rows.map(row => ({ province: standardizeProvinceName(row[0]), city: row[1].trim(), hospital: row[2], bedType: mapBedType(row[3]), // 将中文/印尼文类型映射为英文key available: parseInt(row[4]) || 0, lastUpdated: new Date(row[5]).toISOString(), // ... 添加验证逻辑，比如过滤掉available为负数的行 })).filter(item => item.available > 0); // 只保留有床位的条目 // 4. 按省份分组 const dataByProvince = groupBy(transformedData, 'province'); // 5. 写入本地文件系统 fs.writeFileSync( './data/bed-info.json', JSON.stringify(dataByProvince, null, 2) ); console.log('数据已更新并保存至 ./data/bed-info.json'); }

3.2 Next.js渲染策略的混合运用

Next.js提供了多种渲染方式，我们根据页面特性混合使用，以达到性能与实时性的最佳平衡：

静态生成：用于“关于我们”、“使用指南”、“贡献者列表”等几乎不变的内容。这些页面在构建时生成HTML，直接通过CDN分发，速度极快。
```
// pages/about.js export default function About() { ... } // 无需getStaticProps，因为内容固定
```
带数据的静态生成：用于各省市的主页。我们在构建时（getStaticPaths+getStaticProps）调用数据获取函数，读取我们预先准备好的JSON文件，为每个省份生成一个静态页面。这保证了极快的访问速度。
```
// pages/provinces/[province].js export async function getStaticPaths() { const provinces = await getAllProvinceSlugs(); // 从数据中读取所有省份标识 return { paths: provinces.map(p => ({ params: { province: p } })), fallback: 'blocking', // 关键：处理新增省份 }; } export async function getStaticProps({ params }) { const data = await getProvinceData(params.province); // 读取对应省份的JSON数据 return { props: { data }, revalidate: 3600 }; // 增量静态再生成：每1小时尝试更新一次 }
```
这里使用了fallback: 'blocking'和revalidate。这意味着：
1. 构建时已知的省份会生成静态页面。
2. 如果用户访问一个构建时还不存在的省份链接（比如数据源新增了一个省份），Next.js会在首次请求时服务端渲染这个页面，并将其缓存，后续请求则直接提供静态文件。
3. 即使对于已生成的静态页面，每过1小时（revalidate: 3600），Next.js也会在后台尝试用新数据重新生成页面，下次访问时用户将看到更新后的内容。这完美满足了“信息延迟小于一小时”的要求。
客户端渲染：用于页面内复杂的交互过滤，比如“按城市筛选”、“按床位类型筛选”。这些交互在首屏静态内容加载完成后，由React在客户端接管。我们使用useState和useEffect或SWR来处理客户端状态和数据获取，确保核心内容优先展示。

注意事项：revalidate并不是精确的定时器。它只表示“页面陈旧后，下一个请求将触发重新生成”。对于访问量极低的页面，可能远超过1小时才更新。对于这类实时性要求极高的数据，我们后来引入了更积极的策略，例如在数据更新后主动调用Next.js的On-Demand RevalidationAPI来触发特定页面的立即重建。

3.3 性能优化实战细节

性能不是空谈，我们通过一系列具体措施来兑现承诺：

图片优化：所有图片都通过Next.js的<Image />组件处理，自动提供WebP等现代格式，并实现懒加载和尺寸优化。
字体优化：使用next/font进行Google字体的自动托管和优化，消除布局偏移和外部资源依赖。
代码分割与懒加载：利用Next.js基于页面的自动代码分割，以及React.lazy和动态导入（import()）来拆分非关键组件（如复杂的图表库），减少初始包大小。
关键CSS内联：使用Tailwind CSS时，通过配置确保关键路径的CSS被内联到HTML中，避免因等待CSS文件而阻塞渲染。
第三方脚本管理：对于Google Analytics等第三方脚本，我们将其设置为异步加载，并使用next/script组件的strategy属性（如lazyOnload）进一步推迟其加载，绝不阻塞主线程。

4. 开发流程、测试与协作规范

一个由数十名志愿者协作的项目，没有严格的流程和规范是无法维持代码质量和开发效率的。我们建立了一套基于GitHub的标准化工作流。

4.1 本地开发环境搭建

对于新贡献者，上手极其简单，这降低了参与门槛：

git clone https://github.com/kawalcovid19/wargabantuwarga.com.git cd wargabantuwarga.com yarn install # 使用Yarn，确保依赖树一致 yarn fetch-wbw # 运行脚本，获取最新数据到本地 yarn dev # 启动开发服务器，访问 http://localhost:3000

yarn fetch-wbw这个命令是关键，它让开发者能在本地获得与生产环境一致的数据，进行真实的开发和测试。

4.2 测试策略：以用户行为为中心

我们使用React Testing Library和Cypress进行测试，并严格遵守其哲学：

单元与集成测试（React Testing Library）：
- 查询优先级：我们强制要求使用优先考虑可访问性的查询方式（如getByRole，getByLabelText），而不是脆弱的getByTestId。这反过来促进了我们编写更具可访问性的组件。
- 测试外观与消失：对于加载状态、弹窗、 toast 消息等，我们测试它们是否在正确的时间出现和消失，而不是测试其内部状态。
- 交互而非事件：我们模拟用户的交互（如user.click(button)），而不是直接触发DOM事件（如fireEvent.click）。这能更真实地测试组件行为，因为user.click会触发一系列关联事件（如focus）。
```
// 好的测试：模拟用户交互 import { render, screen } from '@testing-library/react'; import userEvent from '@testing-library/user-event'; test('搜索框输入后显示结果', async () => { render(<SearchPage />); const input = screen.getByRole('searchbox'); await userEvent.type(input, 'Jakarta'); expect(await screen.findByText(/一些关于雅加达的结果/)).toBeInTheDocument(); });
```
端到端测试（Cypress）：用于测试关键的用户流程，例如“从首页导航到雅加达页面，应用床位类型过滤器，并看到列表更新”。Cypress测试在CI/CD流水线中运行，确保核心功能始终正常。

4.3 代码审查与CI/CD

每个Pull Request都会自动触发GitHub Actions工作流，运行以下检查：

测试套件：确保新代码不会破坏现有功能。
代码风格检查：使用ESLint和Prettier保持代码一致性。
类型检查：使用TypeScript（项目后期引入）捕获潜在的类型错误。
性能预算检查：通过Lighthouse CI，我们为Core Web Vitals设定了性能预算。如果PR导致LCP、FID或CLS退化到阈值以下，CI会失败，PR无法合并。这强制所有贡献者都必须关注性能影响。
构建检查：确保Next.js构建能成功完成。

只有通过所有自动化检查的PR，才会由核心维护者进行人工代码审查。审查不仅看代码正确性，也看是否符合项目原则（是否引入了不必要的包？是否影响了可访问性？）。

5. 遇到的挑战与解决方案实录

在项目推进过程中，我们遇到了许多典型的技术和协作挑战。

5.1 数据一致性与错误处理

问题：Google Sheets的数据是自由格式的，志愿者编辑时可能出现拼写错误、格式不一致（如日期写成“01-02-2021” vs “2021/02/01”）、甚至意外删除整列的情况。
解决方案：
1. 强化数据清洗脚本：在转换JSON之前，加入更严格的验证和标准化逻辑。对于无法自动修复的错误数据，脚本会记录警告并跳过该条目，而不是让整个流程失败。
2. 建立数据质量监控：我们创建了一个简单的仪表板，展示数据获取的成功率、每条目的最后更新时间、以及数据中的异常数量（如负数的床位）。这帮助内容团队及时发现数据源的问题。
3. 设计容错UI：前端组件对数据缺失或格式异常要有韧性。例如，如果某个医院条目缺少电话号码，则相关按钮显示为禁用状态并提示“信息暂缺”，而不是让整个页面崩溃。

5.2 性能与实时性的拉锯战

问题：我们希望页面是静态的（快），但又希望数据是最新的（实时）。revalidate虽好，但对于突发性的、重要的数据更新（如某医院突然有空床位），一小时的延迟仍可能太长。
解决方案：采用分层缓存策略。
1. 页面级缓存：使用revalidate（ISR）保证基线更新频率。
2. 数据层客户端轮询：对于最关键的资源列表页面，我们在客户端使用SWR或React Query，在页面加载后，静默地、以更短的间隔（如每5分钟）向一个API端点请求数据增量。当检测到新数据时，无缝更新UI并给出“数据已更新”的温和提示。这样，用户首屏看到的是快速的静态页面，随后获得近乎实时的数据。
3. On-Demand Revalidation：当我们的后台系统通过监控发现数据源有重大更新时，可以主动调用Next.js提供的API，立即清除特定页面的缓存，触发下一次访问时的重建。

5.3 可访问性（A11y）的持续斗争

问题：开发者容易忽略可访问性，导致屏幕阅读器用户无法使用网站。
解决方案：
1. 工具化：在CI中集成axe-core进行自动化可访问性测试。在开发时使用浏览器插件（如axe DevTools）进行扫描。
2. 代码审查清单：在PR模板中加入可访问性检查项，例如：“是否为所有图片提供了alt文本？”、“交互元素是否可以通过键盘访问？”、“颜色对比度是否足够？”。
3. 语义化HTML：强制使用正确的HTML标签（<nav>，<main>，<button>而非<div onClick>），并确保标题层级（<h1>到<h6>）结构清晰。

5.4 管理一个大型开源贡献社区

问题：如何高效处理来自50多位贡献者的数百个Issues和PR？如何保证代码质量不滑坡？
解决方案：
1. 清晰的贡献指南：我们撰写了详细的双语（英语和印尼语）贡献指南，说明了开发环境设置、代码风格、提交信息规范、PR流程等。
2. 标签（Labels）与模板：使用GitHub Issues和PR模板引导贡献者提供必要信息。使用标签（如good first issue，bug，enhancement，help wanted）对任务进行分类，方便新贡献者入门。
3. 机器人辅助：使用@all-contributors机器人自动在README中更新贡献者列表，认可代码、文档、设计、创意等各类贡献，极大地激励了社区。
4. 核心维护者轮值：设立核心维护者小组，并安排轮值制度来处理日常的PR审查和Issue分类，避免 burnout。

6. 项目工具链与基础设施

一个高效的项目离不开趁手的工具和稳定的基础设施。

版本控制与协作：GitHub。用于代码托管、Issue跟踪、PR审查和CI/CD。
持续集成/持续部署：GitHub Actions。我们配置了多个工作流：
- test.yml：在每次提交和PR时运行测试。
- deploy.yml：在代码合并到主分支后，自动构建并部署到生产环境（Netlify）。
- lighthouse-ci-prod.yml：定期或在每次部署后，对生产网站运行Lighthouse性能测试，并将结果提交回仓库，以便跟踪性能趋势。
托管：Netlify。其全球CDN、无缝的Git集成、以及支持Next.js所有特性（如ISR、Serverless Functions）的能力，使其成为不二之选。它提供了免费的SSL、自定义域名和出色的部署预览功能。
性能监控：Lighthouse CI、WebPageTest。我们不仅在生产环境监控，还将性能测试集成到开发流程中。
错误监控：后期我们集成了Sentry，用于捕获前端JavaScript运行时错误，帮助我们快速定位和修复线上问题。

7. 总结与反思

回顾整个Warga Bantu Warga项目，它是一次将现代Web开发最佳实践应用于紧急社会需求的成功尝试。技术栈的选择（Next.js, React, Tailwind CSS）被证明是正确且高效的，它们在性能、开发体验和可维护性之间取得了绝佳的平衡。

我个人最深的体会是，在这样一个以速度和可靠性为生命的项目中，约束和原则比技术本身更重要。我们一开始就定下的“性能、可访问性、实时性”铁律，像灯塔一样指引着每一个技术决策。每当有新的想法或需求提出，我们首先问的不是“能不能做”，而是“做了之后，对我们的核心指标有什么影响？”。这种以终为始、数据驱动的思维方式，是项目在混乱中保持有序和高效的关键。

对于想要构建类似公共信息平台或高性能内容网站的开发者，我的建议是：