06 部署运行

项目：html5-dataviz ｜ 版本：v1.0 ｜ 生成日期：2026-10-05 ｜ 依据：源码分析

1. 环境要求

2. 本地启动步骤（命令级）

cd html5-dataviz
pnpm install                 # 1. 安装依赖（frozen-lockfile 由 CI 使用）
pnpm dev                     # 2. 启动开发服务器 → http://localhost:5566
                             #    （"dev" 脚本 = vite --port 5566，端口在 package.json 写死）
pnpm typecheck               # 3.（可选）vue-tsc --noEmit，CI 阻塞项
pnpm lint                    # 4.（可选）ESLint
pnpm test                    # 5.（可选）Vitest 单元测试（run 模式）
pnpm test:watch              #    或监视模式

开发注意事项：

• 首次启动会做依赖预构建，three 生态体量大，耐心等待；optimizeDeps target 已调至 esnext，若自行改动依赖出现顶层 await 报错，检查是否绕开了该配置。
• 自动导入：unplugin-auto-import 与 unplugin-vue-components（vite.config.ts）会在 dev/build 时改写 auto-imports.d.ts 与 components.d.ts——这两个文件是生成物，勿手改。
• 公共组件（AppButton/AppHeader/AppIcon 等）在 components.d.ts 中有全局类型声明，SFC 内可不 import 直接使用；但源码中普遍仍显式 import（可读性优先）。
• Element Plus 按需：组件经 ElementPlusResolver 自动引入，但按钮/输入框的样式在 src/main.ts 显式引入了两条 CSS（注释说明了原因）。

3. 构建与静态部署

pnpm build      # NODE_OPTIONS='--max-old-space-size=8192' vite build → dist/
pnpm preview    # 本地预览构建产物

产物特征（由 vite.config.ts 决定）：

• vendor 五桶分包：echarts-gl-vendor、echarts-vendor（echarts + vue-echarts + @echarts-x）、antv-vendor（@antv/*）、three-vendor（three 及生态）、vendor（vue/vue-router/pinia/@vueuse/element-plus/dayjs 框架运行时桶）。manualChunks 只归组 node_modules，src 代码（含按库懒加载的 JSON）不进 vendor 桶——注释记录了"Vue 运行时曾被并进 echarts-vendor、入口 modulepreload 了 9.3MB echarts"的修复史。
• 按路由/按需 chunk：1617 个示例 SFC（import.meta.glob）、三个库 JSON（动态 import）、22 个大屏（bigscreenComponentMap 懒加载器）各自异步分片。
• public/ 原样拷贝：含约 800MB 的 three 资产（public/threejs-official 419M、three-project 192M、external-examples 180M）与 71MB echarts-data，README 部署一节明确"将 dist/ 交由任意静态服务器托管（无后端依赖）"。

部署要点：

1. History 路由回退：src/router/index.ts 使用 createWebHistory()，静态服务器必须把所有未命中路径回退到 index.html（SPA fallback），否则刷新非根路径会 404。
2. 内网/离线部署：运行时零外链是硬前提——index.html 仅有的 fonts.googleapis.com 字体外链属于"渐进增强"（加载失败回落系统字体，不阻塞功能）；smoke 的外链断言正则（jsdelivr.net|aliyun.com|youbao.xyz|alipayobjects.com）必须保持通过。部署到内网时可考虑把字体一并本地化（⚠️ 待确认：仓库内未见到字体本地化资产）。
3. 服务器带宽/磁盘：dist 体积以 GB 计（public 三大 three 目录占大头），按需裁剪未被引用的资产前应先跑 scripts/sweep-fallback.mjs / sweep-three.mjs 类治理脚本核对引用关系。
4. CI（.github/workflows/ci.yml，push main / PR 触发）：pnpm install --frozen-lockfile → pnpm lint → pnpm typecheck → pnpm test → pnpm build，四道闸门全绿才算通过；smoke 未纳入 CI（需要起服务与浏览器，本地/发布前执行）。

4. 测试体系

4.1 单元测试（Vitest）

vitest.config.ts：environment happy-dom、globals: true、include src/**/*.{test,spec}.{ts,tsx}、testTimeout: 20_000（注释：图表库 JSON 体量大，懒加载导入在 node 下偏慢）、setupFiles vitest.setup.ts（全局 stub 掉 element-plus 的 message 样式模块，注释说明 vitest 下 element-plus 被外置化导致 CSS 无法加载）。

19 个测试文件的覆盖矩阵：

覆盖率：@vitest/coverage-v8 已安装，执行 pnpm vitest run --coverage 即可产出 V8 覆盖率报告；package.json 未定义独立 coverage script、vitest.config.ts 未配置 coverage 阈值（⚠️ 待确认：覆盖率门禁是否在其他流水线中设置）。

4.2 冒烟测试（smoke-shots 机制）

pnpm test:smoke（node scripts/smoke.mjs）需要先起服务：pnpm dev 或 pnpm build && pnpm preview，默认 BASE_URL=http://localhost:5566，可用环境变量覆盖（BASE_URL=https://xxx node scripts/smoke.mjs）。

脚本流程（scripts/smoke.mjs，104 行）：

1. 页面遍历：10 个代表页面（首页、三库列表、大屏列表、sales-analysis/business-dashboard/dashboard 三个大屏详情、echarts area-simple 详情、three machineRoom 详情），逐页 goto(waitUntil: networkidle) → HTTP 状态断言 → pageerror 收集 → 等待 2500ms → 截图存 smoke-shots/{name}.png。
2. 大屏 canvas 断言：sales-analysis 详情 document.querySelectorAll('canvas').length > 0（"echarts 渲染证据"）。
3. 图表详情断言：area-simple 详情用 waitForFunction 显式轮询 canvas 出现（20s 超时，注释解释固定等待会被 echarts-vendor 冷启动拖垮），且 getByText('渲染失败') 计数为 0。
4. 源码弹窗断言：点开"查看源代码"→ .scm 出现 → 关闭 → waitForSelector({state:'detached'})，验证 Transition 完整走完。
5. GL 兜底链路断言：/charts/echarts/gl-lines3d-airline-on-globe 覆盖"api-async 求值 + echarts-gl 预载 + fetch 数据文件"整条兜底通路，canvas > 0、无"渲染失败"、无"加载资源失败"。
6. 外链零请求断言：监听 page.on('request')，命中 jsdelivr.net|aliyun.com|youbao.xyz|alipayobjects.com 即收集，最后统一判失败。
7. 任何失败汇总打印并以退出码 1 结束；全部通过打印"冒烟全部通过"。

smoke-shots/ 里的截图是运行产物（.gitignore 已忽略，评审时人工目检），不是测试输入。

4.3 工具脚本速查（scripts/）

5. 新增一个可视化案例——标准操作流程（SOP）

以"新增一个 ECharts 案例"为主线（antv/three 差异附后）。

第 1 步：创建本地 SFC

在 src/chart-examples/echarts/{分类目录}/{id}.vue 新建文件。id 即身份：必须与后续 JSON 条目、清单条目、缩略图文件名完全一致（kebab-case，全站唯一）。模板遵循 docs/CODE_TO_VCHART_GUIDE.md 规范：

<template>
  <div class="demo-container">
    <EChartDemo :option="option" />
  </div>
</template>

<script setup>
import EChartDemo from '../../EChartDemo.vue'

// 简单示例：普通对象；需动态更新则用 ref 并整体/局部替换 option.value
const option = {
  xAxis: { type: 'category', data: ['Mon', 'Tue', 'Wed'] },
  yAxis: { type: 'value' },
  series: [{ data: [150, 230, 224], type: 'bar' }],
}
</script>

<style scoped>
.demo-container {
  position: relative;
  width: 100%;
  height: 100%;
  min-height: 280px;
  border-radius: inherit;
  overflow: hidden;
}
</style>

要点：需要 echarts.registerMap / setInterval / 事件交互时，不要在 SFC 里自行 init——用 EChartDemo 的 setup(ctx) 钩子（返回清理函数）或按手册改写为 <v-chart> 响应式写法；GL 系列在脚本内 import 'echarts-gl'（放在 echarts import 之后）。

第 2 步：注册清单条目（manifest）

在 src/chart-examples/manifest.ts 的 echartsLocalManifest 数组追加（按 id 字母序插入，与现有风格一致）：

{
  id: 'my-new-demo',
  title: '我的新示例',
  category: '柱状图',           // 尽量复用已有分类（37 类之一），新分类会出现在侧栏
  tags: ['柱状图', '动画'],
},

注意：manifest.ts 头部标注"由 server/scripts/gen-charts-local.ts 自动生成，请勿手改"——手工追加条目是当前仓库内的实际可行做法（⚠️ 待确认：server 生成器仓库未随项目提供，无法验证再生成是否会覆盖手工条目；建议追加后 git 提交留痕）。

第 3 步：注册 JSON 元数据条目

在 src/data/charts/echarts.json 追加完整 schema 条目（19 字段，见 04 篇第 1 节）。这一步不可省略：列表页数据完全来自 JSON（getChartExamples），没有 JSON 条目的案例不会出现在列表里。由于存在本地 SFC，按瘦身规则不要写 optionCode/componentCode/initCode；loaderKind 填 option（或 api-async，与同类条目保持一致）；thumbnail 可先置 null（列表回落 /chart-thumbs/{id}.webp）。

第 4 步：准备缩略图

生成 640 宽 WebP 放入 public/chart-thumbs/{id}.webp（推荐直接用 node scripts/gen-thumbs-webp.mjs 的同参数规格：宽 640、质量 78、保留透明通道）。无缩略图时列表卡片显示 📊 占位，功能不受阻。

第 5 步：更新守恒测试数字

src/data/charts/__tests__/charts-data.test.ts 中 FILES 常量把 echarts 条数硬编码为 expected: 348——新增 1 条后改为 349。若新增的是 antv/three 案例，对应修改 351/989。然后跑 pnpm test 确认守恒断言全绿（该测试还会校验 SFC↔JSON id 互不缺，第 1、3 步任何遗漏都会在此暴露）。

第 6 步：本地验证

pnpm dev
# 浏览器访问 http://localhost:5566/charts/echarts
# 1) 列表出现新卡片（搜标题或按分类筛选）
# 2) 点进详情：canvas 渲染正常、无"渲染失败"
# 3) 打开源码弹窗：内容与 SFC 一致；下载按钮可用
pnpm typecheck && pnpm lint && pnpm test
# （推荐）起 dev 后执行冒烟，必要时把新案例加进 scripts/smoke.mjs 的 PAGES
pnpm test:smoke

差异化流程

• 新增 antv 案例：第 1 步改为自驱 SFC（onMounted 中 new Plot(containerRef.value, options) + render()，无需 EChartDemo）；manifest 加进 antvLocalManifest；JSON 加进 antv.json（loaderKind: 'antv-config'）。
• 新增 three 案例：规范路径是用 node scripts/gen-three-registry.mjs 从 curio 源迁移（自动完成组件拷贝到 src/chart-examples/three/{source}/{category}/、three.json 与 three-manifest.ts 生成、资产裁剪拷贝与四项校验）；手工新增需同步三处——SFC（基于 ExampleScene 壳）、three-manifest.ts、three.json（loaderKind: 'local'，按需 globals.ASSET_HOST），并保证资产放入 public/ 对应根路径。
• 新增大屏：见 02 篇第 7 节——新建 src/views/bigscreen/{name}/{Name}Page.vue（根节点用 DatavContainer），同时在 src/config/bigscreenData.ts 与 src/config/bigscreenComponents.ts 各加一条（两处键必须一致，测试锁定），缩略图放 public/bigscreen-thumbnails/{id}.webp，并跑 src/config/__tests__/bigscreenComponents.test.ts 验证。
• 下线案例：同时删除 SFC、manifest 条目、JSON 条目与缩略图，并同步 charts-data.test.ts 的 expected 数字（历史先例：apexcharts/chartjs/d3 三库于 2026-10 整体删除，README 有记录）。

6. 常见问题排查速查