Angular生产构建后leaflet.heat外部库失效问题排查

问题场景 #

我在构建一个使用leaflet.heat库的Angular 18应用，导入及使用代码如下：

import * as L from 'leaflet';
import 'leaflet.heat';

// 使用示例：
private addHeatmapToMap(heatmapData: L.HeatLatLngTuple[]) {
  let heatmap = L.heatLayer(heatmapData, { 
    radius: 10, 
    max: 200, 
    gradient: { 0.1: 'yellow', 0.4: 'orange', 0.6: 'red', 0.8: 'white' }, 
    minOpacity: 0.8 
  });
  // ...后续逻辑
}

ng serve调试时功能完全正常，但执行ng build --configuration production --output-path=/dist构建生产包（用于Docker容器）后，L.heatLayer等依赖leaflet.heat的函数直接失效。推测是Angular生产构建的tree-shaking机制，把未被"直接引用"的leaflet.heat导入给移除了，但不知道如何阻止这种行为。

依赖版本 #

"angular": "18",
"leaflet": "^1.9.4",
"leaflet.heat": "^0.2.0",
"@types/leaflet": "^1.9.12",
"@types/leaflet.heat": "^0.2.4"

Docker构建脚本 #

#################
# Build the app #
#################
FROM node:22-alpine AS build

WORKDIR /app

RUN npm install -g @angular/cli

COPY package.json package-lock.json ./
RUN npm install --fetch-timeout=600000 
COPY . .

RUN ng build --configuration production --output-path=/dist

################
# Run in NGINX #
################
FROM nginx:alpine

COPY --from=build /dist/browser /usr/share/nginx/html
COPY --from=build /app/nginx.conf /etc/nginx/nginx.conf

# 容器启动时，用环境变量替换env.js
CMD ["/bin/sh",  "-c",  "envsubst < /usr/share/nginx/html/assets/environment/env.template.js > /usr/share/nginx/html/assets/environment/env.js && exec nginx -g 'daemon off;'"]

解决方案 #

方法1：显式引用库导出（强制保留导入） #

leaflet.heat是通过给L对象挂载扩展方法的方式工作的，Angular的tree-shaking会判定这个导入没有被直接使用而丢弃。可以通过显式引用库的导出（哪怕只是赋值给一个无用变量），告诉构建工具保留这个导入：

import * as L from 'leaflet';
import * as LeafletHeat from 'leaflet.heat';

// 新增此行，强制构建工具保留leaflet.heat的导入
const _ = LeafletHeat;

// 后续使用逻辑不变
private addHeatmapToMap(heatmapData: L.HeatLatLngTuple[]) {
  let heatmap = L.heatLayer(heatmapData, { /* 配置项 */ });
}

方法2：在angular.json中排除leaflet.heat的tree-shaking #

修改项目根目录下的angular.json，找到对应项目的build配置，在优化规则中排除leaflet.heat：

"projects": {
  "你的项目名称": {
    "architect": {
      "build": {
        "options": {
          "optimization": {
            "scripts": {
              "exclude": ["leaflet.heat"]
            }
          }
        },
        "configurations": {
          "production": {
            // 确保production配置继承或启用上述优化规则
          }
        }
      }
    }
  }
}

方法3：在polyfills.ts中全局导入 #

如果项目没有polyfills.ts，可手动创建，在这里全局导入leaflet.heat，确保应用启动时就加载该库，避免被tree-shaking移除：

// src/polyfills.ts
import 'leaflet';
import 'leaflet.heat';

然后在angular.json的build配置中添加polyfills引用：

"build": {
  "options": {
    "polyfills": ["src/polyfills.ts"]
  }
}

方法4：使用require代替import（备选方案） #

如果上述方法都不生效，可尝试用CommonJS的require语法，这种方式通常不会被tree-shaking处理：

import * as L from 'leaflet';
// 替换import为require
require('leaflet.heat');

// 后续使用逻辑不变
private addHeatmapToMap(heatmapData: L.HeatLatLngTuple[]) {
  let heatmap = L.heatLayer(heatmapData, { /* 配置项 */ });
}

内容的提问来源于stack exchange，提问作者nck