在 Node/Express 服务中嵌入 Kepler.gl:monorepo 外独立运行的完整示例指南
在 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.lockis 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 同时承担两层职责:
- 构建前端:将
src/main.js打包为dist/bundle.js(IIFE 格式、浏览器平台,见 examples/node-app/esbuild.config.mjs); - 开发服务器:
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}/`);
});
它的关键设计有两点:
- 静态资源托管:
express.static将dist目录直接对外暴露,打包产物bundle.js、index.html均可直接访问; - 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。本示例支持三种注入方式:
- 环境变量注入(推荐):启动前设置环境变量
MapboxAccessToken,esbuild 会在编译期通过define将其替换进代码:MapboxAccessToken=pk.xxxx yarn start - 本地
.env文件:esbuild 配置中引入了dotenvRun插件并指定root: '../../.env'(指向 kepler.gl 仓库根目录下的.env文件,见 examples/node-app/esbuild.config.mjs),结合start-local脚本的NODE_ENV=local即可加载本地环境变量; - 直接修改源码占位符:将 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。
工作流程总结
把上述环节串起来,整个示例的运行时序是:
yarn start→ esbuild 读取 esbuild.config.mjs,把src/main.js打包成dist/bundle.js,并把index.html拷贝到dist/;- esbuild 启动
:3000开发服务器并 watch 源码,代码变更时通过EventSource自动刷新浏览器; - 浏览器加载
index.html,执行bundle.js,React 创建Provider→App→KeplerGl组件树; store.js中的keplerGlReducer开始接收并管理地图状态,KeplerGl组件以map1为 id 渲染地图界面;- 如需以 Express 形态部署:
yarn build生成产物后,运行 server.js 即可由 Express 在:3000提供同样的页面。
扩展到真实业务
这个示例虽然精简,但已经覆盖了把 kepler.gl 嵌入 Node 服务所需的全部骨架。你可以在此基础上扩展:
- 加载数据:在
App组件中通过useEffect调用addDataToMapaction,将 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 能力,因此地图组件只能在客户端挂载,服务端只负责静态托管与回退。
参考资料
- 示例入口文档:examples/node-app/README.md
- 依赖与脚本定义:examples/node-app/package.json
- Express 托管服务器:examples/node-app/server.js
- esbuild 构建/开发配置:examples/node-app/esbuild.config.mjs
- Redux store 组装:examples/node-app/src/store.js
- KeplerGl 组件挂载:examples/node-app/src/app.js
- React 入口:examples/node-app/src/main.js
- 示例总览:examples/README.md