在 Node/Express 服务中嵌入 Kepler.gl:monorepo 外独立运行的完整示例指南

原创2026-09-22 17:54:331,899 阅读
文章标签:数据可视化前端GIS

在 Node/Express 服务中嵌入 Kepler.gl:monorepo 外独立运行的完整示例指南

Kepler.gl 的官方示例 examples/node-app 演示了如何在基于 Express 的 Node.js 后端服务中嵌入 Kepler.gl 地图应用,形成「Express 托管静态资源 + 前端 React/Redux 渲染地图」的经典部署形态。读完本文,你将掌握该示例的安装、启动、构建与本地调试全流程,理解 touch yarn.lock 的 monorepo 隔离原理、esbuild 开发服务器与 Express 静态托管的协作方式,以及 Mapbox Token 等环境变量的注入机制,可直接迁移到自己的 Node 服务项目中。

示例概述:一个「前后端一体」的 kepler.gl 应用

examples/node-app 是 kepler.gl 仓库中面向 Node/Express 场景的官方示例,对应文档见 examples/node-app/README.md。它展示的核心模式是:

  • 用 Express 作为 Web 服务器,托管构建产物并实现 SPA 路由回退;
  • 用 React + Redux 渲染 kepler.gl 地图组件;
  • 用 esbuild 完成打包、开发服务器与热更新(HMR)。

整个示例的代码结构如下:

examples/node-app/
├── package.json          # 独立项目的依赖与脚本
├── esbuild.config.mjs    # esbuild 构建/开发服务器配置
├── server.js             # Express 静态托管服务器
├── index.html            # 页面入口模板
├── tsconfig.json         # TypeScript 配置(JSX、模块解析)
└── src/
    ├── main.js           # React 入口:挂载 Provider + App
    ├── app.js            # 渲染 KeplerGl 组件(含 Mapbox Token 注入)
    ├── app-reducer.js    # 自定义应用级 reducer
    └── store.js          # Redux store:挂载 keplerGlReducer

其中前端源码(src/ 目录)在仓库内由 examples/node-app/tsconfig.json 的 include: ["src"] 纳入类型检查,JSX 编译目标为 react-jsx,模块解析采用 bundler 模式。

前置条件

运行该示例前,需要确保本机具备:

  • Node.js 环境(示例使用 node:child_process、node:fs 等 Node 内置模块,见 examples/node-app/esbuild.config.mjs);
  • Yarn 包管理器(安装与启动命令均以 yarn 驱动);
  • 一个 Mapbox Access Token(可选但推荐,用于渲染真实底图,详见下文「配置 Mapbox Token」小节)。

第一步:安装依赖

进入示例目录后,官方 README 给出的安装命令是:

touch yarn.lock && yarn

首次执行时必须先 touch yarn.lock,这一步的作用是让 Yarn 将该目录识别为独立项目,而不是 kepler.gl monorepo 的一部分。README 中对此有明确说明:

touch yarn.lock is needed the first time so Yarn treats this as a standalone project, independent from the kepler.gl monorepo.

也就是说,examples/node-app 虽然位于 kepler.gl 仓库内部,但通过本地 yarn.lock 的存在,Yarn 会按独立工程处理它,避免与仓库根目录的 workspace 解析逻辑互相干扰。如果你的环境中没有 yarn.lock 文件(或尚未生成),直接 yarn 可能无法正确安装,务必先执行 touch yarn.lock。

从 examples/node-app/package.json 可以看到本示例的关键依赖:

依赖 版本(示例锁定) 作用
@kepler.gl/components ^3.3.0-alpha.6 提供 KeplerGl 地图组件
@kepler.gl/reducers ^3.3.0-alpha.6 提供 keplerGlReducer 与 enhanceReduxMiddleware
express ^4.17.1 Web 服务器 / 静态资源托管
react / react-dom ^19.0.0 UI 渲染
react-redux ^9.1.0 Redux 与 React 桥接
redux ^5.0.0 状态管理
styled-components 6.4.3 样式方案(kepler.gl 内部依赖)

开发依赖方面,示例使用 esbuild(^0.25.0)作为打包器,并配合 esbuild-plugin-copy、esbuild-plugin-replace、@dotenv-run/esbuild 完成资源拷贝、常量替换与 .env 环境变量加载。

第二步:启动应用

依赖安装完成后,启动命令同样是 README 中给出的:

yarn start

该命令实际执行的是 node esbuild.config.mjs --start(见 examples/node-app/package.json),由 esbuild 同时承担两层职责:

  1. 构建前端:将 src/main.js 打包为 dist/bundle.js(IIFE 格式、浏览器平台,见 examples/node-app/esbuild.config.mjs);
  2. 开发服务器:esbuild.context().serve() 监听 dist 目录、默认端口 3000,并通过注入 EventSource 热更新脚本实现代码变更后的自动刷新(examples/node-app/esbuild.config.mjs)。

启动成功后,终端会打印:

kepler.gl node-app example running at http://localhost:3000

并调用系统默认浏览器自动打开页面(macOS 使用 open、Linux 使用 xdg-open、Windows 使用 cmd /c start,见 examples/node-app/esbuild.config.mjs)。

三种运行脚本对比

package.json 中共定义了三个脚本,适用于不同场景:

脚本 命令 适用场景
yarn start node esbuild.config.mjs --start 开发模式:watch + serve + 自动打开浏览器
yarn build node esbuild.config.mjs --build 生产构建:minify + tree-shaking + 输出 metafile
yarn start-local NODE_ENV=local node esbuild.config.mjs --start 加载本地 .env 环境的开发模式

在 monorepo 根目录下,也可以通过根级 package.json 提供的快捷脚本直接启动本示例:

yarn start:node-app   # 等价于 yarn install-and-start examples/node-app start-local

该命令会先执行 install-and-start 脚本完成安装再以 start-local 启动,适合从仓库根目录一键体验。

生产构建模式

如果需要生成可供 Express 托管的静态产物,执行:

yarn build

该模式会启用 minify: true、treeShaking: true、drop: <a href="https://link.gitcode.com/i/d3b2f4a95ea97663e31e2396c9cd913c" target="_blank">'console', 'debugger'] 并写入 dist/esbuild-metadata.json 元数据(见 [examples/node-app/esbuild.config.mjs),最终产物供 server.js 托管。

Express 服务器如何工作

examples/node-app/server.js 是一个极简但完整的 Express 应用:

const ADDRESS = '0.0.0.0';
const PORT = process.env.PORT || 3000;

// Serve static files from dist
app.use(express.static(path.join(__dirname, 'dist')));

// Always return index.html for any route (SPA)
app.get('*', function response(req, res) {
  res.sendFile(path.join(__dirname, 'dist', 'index.html'));
});

app.listen(PORT, ADDRESS, function onStart(err) {
  // ...
  console.info(`==> 🌎 Listening on port ${PORT}. Open up http://${ADDRESS}:${PORT}/`);
});

它的关键设计有两点:

  1. 静态资源托管:express.static 将 dist 目录直接对外暴露,打包产物 bundle.js、index.html 均可直接访问;
  2. SPA 路由回退:app.get('*') 将任何未命中静态文件的路径都回退到 index.html,从而支持前端路由(这是单页应用的通用做法)。

同时,服务器监听地址硬编码为 0.0.0.0,端口默认 3000,可用环境变量 PORT 覆盖。这意味着同一套产物既可以由 esbuild 开发服务器提供(yarn start),也可以由 Express 提供(yarn build 后手动 node server.js),两条路径互不冲突。

前端如何嵌入 Kepler.gl

React 入口

examples/node-app/src/main.js 是标准的 React 18+ 挂载方式,使用 createRoot 渲染 <Provider> 包裹的 <App />:

const Root = () => (
  <Provider store={store}>
    <App />
  </Provider>
);
const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(<Root />);

页面模板 examples/node-app/index.html 提供了 #root 挂载点,并引入了 Mapbox GL 与 MapLibre GL 的样式文件。

Redux Store 的组装

kepler.gl 与 Redux 深度集成。在 examples/node-app/src/store.js 中:

import keplerGlReducer, {enhanceReduxMiddleware} from '@kepler.gl/reducers';

const reducers = combineReducers({
  keplerGl: keplerGlReducer,
  app: appReducer
});

const middlewares = enhanceReduxMiddleware([]);
const enhancers = applyMiddleware(...middlewares);

export default createStore(reducers, {}, compose(enhancers));

这里有两个必须掌握的点:

  • keplerGlReducer 挂载在 keplerGl 字段下,这是 kepler.gl 官方推荐的默认挂载位置(KeplerGl 组件默认以 keplerGl 作为 state 根路径,除非组件上显式传入 reduxKey 等自定义配置);
  • enhanceReduxMiddleware 是 @kepler.gl/reducers 提供的中间件增强器,它负责把 kepler.gl 内部需要的中间件(如处理大规模数据、forwardActions 相关逻辑)注入进来,同时保留你传入的自定义中间件数组。上例传入空数组 [],表示只启用 kepler.gl 内置能力。

自定义的 appReducer(examples/node-app/src/app-reducer.js)演示了如何在 kepler.gl 之外维护应用自身的状态,例如 appName: 'example' 与应用初始化标记。

渲染 KeplerGl 组件

examples/node-app/src/app.js 是地图渲染的核心:

const MAPBOX_TOKEN = process.env.MapboxAccessToken || 'pk.xxx.yyy';

const App = () => {
  // 用 ResizeObserver 实时跟踪容器尺寸
  const containerRef = useRef(null);
  const [dimensions, setDimensions] = useState({width: 0, height: 0});

  useEffect(() => {
    const observer = new ResizeObserver(entries => {
      const {width, height} = entries[0].contentRect;
      setDimensions({width, height});
    });
    observer.observe(containerRef.current);
    return () => observer.disconnect();
  }, []);

  return (
    <StyledWrapper ref={containerRef}>
      <KeplerGl
        mapboxApiAccessToken={MAPBOX_TOKEN}
        id="map1"
        width={dimensions.width}
        height={dimensions.height}
      />
    </StyledWrapper>
  );
};

值得注意的工程细节:

  • mapboxApiAccessToken 从 process.env.MapboxAccessToken 读取,该变量由 esbuild 的 define 配置在编译期注入(见 examples/node-app/esbuild.config.mjs),示例中还设置了占位符 'pk.xxx.yyy' 兜底;
  • id="map1" 用于标识 map 实例,在 Redux state 中对应 keplerGl.map1 这一分支,后续可以通过 actions 定向操作该实例;
  • ResizeObserver 动态测量容器尺寸,将 width/height 实时传给 KeplerGl,保证地图能随窗口自适应(外层容器样式为 100vw × 100vh 全屏)。

配置 Mapbox Token

地图底图渲染依赖 Mapbox Access Token。本示例支持三种注入方式:

  1. 环境变量注入(推荐):启动前设置环境变量 MapboxAccessToken,esbuild 会在编译期通过 define 将其替换进代码:
    MapboxAccessToken=pk.xxxx yarn start
    
  2. 本地 .env 文件:esbuild 配置中引入了 dotenvRun 插件并指定 root: '../../.env'(指向 kepler.gl 仓库根目录下的 .env 文件,见 examples/node-app/esbuild.config.mjs),结合 start-local 脚本的 NODE_ENV=local 即可加载本地环境变量;
  3. 直接修改源码占位符:将 examples/node-app/src/app.js 中的 'pk.xxx.yyy' 替换为真实 Token(仅作兜底,不建议在生产中硬编码)。

注意:若使用非 Mapbox 底图服务(如 MapLibre),需要相应调整 index.html 中引入的底图样式资源与 Token 来源,kepler.gl 对自定义地图样式与底图服务提供支持,可参考 docs/api-reference/advanced-usages/custom-map-styles.md。

工作流程总结

把上述环节串起来,整个示例的运行时序是:

  1. yarn start → esbuild 读取 esbuild.config.mjs,把 src/main.js 打包成 dist/bundle.js,并把 index.html 拷贝到 dist/;
  2. esbuild 启动 :3000 开发服务器并 watch 源码,代码变更时通过 EventSource 自动刷新浏览器;
  3. 浏览器加载 index.html,执行 bundle.js,React 创建 Provider → App → KeplerGl 组件树;
  4. store.js 中的 keplerGlReducer 开始接收并管理地图状态,KeplerGl 组件以 map1 为 id 渲染地图界面;
  5. 如需以 Express 形态部署:yarn build 生成产物后,运行 server.js 即可由 Express 在 :3000 提供同样的页面。

扩展到真实业务

这个示例虽然精简,但已经覆盖了把 kepler.gl 嵌入 Node 服务所需的全部骨架。你可以在此基础上扩展:

  • 加载数据:在 App 组件中通过 useEffect 调用 addDataToMap action,将 CSV/GeoJSON 数据(可参考 examples/get-started/src/app.tsx 的加载方式)注入 keplerGl.map1;
  • 自定义 reducer/action:仿照 app-reducer.js 维护应用状态,或参考 examples/custom-reducer 深入定制;
  • 前后端分离:Express 端增加 API 路由提供数据接口,前端 fetch 后喂给 kepler.gl,实现数据服务化;
  • 服务端渲染差异:本示例为纯客户端渲染(CSR),kepler.gl 依赖浏览器 WebGL/Canvas 能力,因此地图组件只能在客户端挂载,服务端只负责静态托管与回退。

参考资料

登录后查看全文
kepler.gl