Tree Shaking 可能静默失效，需从产物、引用、前提三方面排查：一、对象属性访问导致全模块保留，应改用具名导出/导入；二、副作用未声明，需正确配置 sideEffects；三、CommonJS 混用破坏静态分析，优先选用 ESM 替代品；四、基础前提不足，如未启用生产模式、缺失压缩器等。
Tree Shaking 不会报错，但会“静默失效”——代码明明没用，却仍留在打包产物里。排查核心就三点：看产物、查引用、验前提。下面分四类高频场景，直击问题本质和可操作解法。
一、对象属性访问导致的假按需引入
这是最隐蔽也最常被忽略的失效点。看似只用了某个方法，实则整个模块被保留。
-
典型写法：
import utils from './utils'; utils.methodA();—— 即使只调用methodA，utils对象里所有属性（methodB、methodC）都进包 -
命名空间导入无访问：
import * as utils from './utils'; console.log('loaded');—— 没有utils.xxx访问语句，工具可能保守保留全部导出 -
解构但未使用：
import { methodA, methodB } from './utils'; methodA();——methodB虽未调用，但出现在解构中，部分旧版工具无法安全剔除
修复方式：改用具名导出 + 具名导入。把 export default { methodA, methodB } 拆成 export function methodA() {} 和 export function methodB() {}，再用 import { methodA } from './utils' 显式声明依赖。
二、副作用未正确声明
Webpack 默认认为模块有副作用，只要不确定“是否安全删除”，就整块保留。关键在 package.json 的 "sideEffects" 字段。
-
设为
false却有真实副作用：比如模块里执行了localStorage.setItem('init', '1')或import './reset.css'，删掉会导致功能异常 -
漏声明副作用文件：第三方库的 CSS 入口（如
import 'antd/dist/reset.css'）没写进sideEffects数组，Webpack 可能误删 -
顶层副作用代码：模块顶层写了
console.log('init')、window.myLib = {}、Array.prototype.extend = ...，都会被识别为有副作用
验证方法：临时将疑似模块的 sideEffects 设为 false（仅测试），构建后运行看是否报错或样式/行为异常。若异常，说明它真有副作用，必须加进白名单。
DMap GL地图JSAPI（dmapgl）开发指南。用于编写、审查、调试 DMap 地图 API 代码，涵盖地图初始化、覆盖物渲染、图层管理、事件处理、控件交互等任务。当用户提及 dmap、dmapgl、jsapi‑gl 或相关地图开发需求时自动触发。
三、CommonJS 混用破坏静态分析
ESM 的 import 是静态的，require 是运行时动态的——遇到 require，Tree Shaking 就“放弃思考”，整模块照单全收。
-
源码含
require或module.exports：哪怕只有一行，该模块导出就无法被精准分析 -
第三方库是 CommonJS 格式：如老版本
lodash，即使你写import { debounce } from 'lodash'，实际加载的仍是require('lodash')形式 -
Babel 错误转译：启用了
@babel/plugin-transform-modules-commonjs，把export编译成module.exports，等于自废 ESM 武功
绕过方案：优先换 ESM 友好替代品（如 lodash-es）；必须用 CommonJS 库时，改用 const { debounce } = require('lodash')（Webpack 5+ 能做有限优化）；或通过 dynamic import() 延迟加载，至少实现代码分割。
四、基础前提不满足
Tree Shaking 不是默认打开的魔法开关，它依赖几个硬性条件。
-
没开生产模式：Webpack/Rollup 默认只在
mode: 'production'下启用 Tree Shaking，开发模式下usedExports和minimize都不生效 -
没用 ES Module 语法：源码或依赖中存在
require/module.exports，静态分析直接失效 -
压缩工具缺失：Tree Shaking 只负责“标记”未使用代码，真正删除靠 Terser 等压缩器。若没配
optimization.minimizer，标记了也不删 -
动态导入干扰：
if (cond) import('./a.js')或import(`./${name}.js`)会让工具无法确定依赖，保守保留相关模块
快速验证法：构建后打开 dist/assets/index.xxxx.js，搜索一个你确定没用的函数名（如 unusedHelper）。若存在，说明没摇掉；再加一行 import { unusedHelper } from './utils'; 重新构建，对比体积是否增大——无变化说明已生效，增大说明它本就被保留着。
