es modules 浏览器报错分两类：一是 cors 限制（如 file:// 协议下 origin 'null' 错误，需启本地服务器；cdn 或自建服务须返回正确 access-control-allow-origin 头）；二是路径与解析错误（如相对路径计算错误、import map 映射失败、构建后 base 路径不匹配），排查应结合 network 面板检查响应头、状态码及实际返回内容。
ES Modules 在浏览器中运行时，报错通常集中在两类：一类是跨域（CORS）限制，另一类是资源路径或加载逻辑问题。这两类错误表现不同、成因明确，排查时有清晰路径可循。
一、CORS 报错：Access to script at 'file://...' 或 'https://...' blocked
这类错误本质是浏览器拒绝加载模块，因为模块请求违反了同源策略，且服务端未正确响应 CORS 头（或根本没走 HTTP 协议）。
-
file:// 协议下直接双击打开 HTML 文件：ESM 不支持本地 file:// 加载，会报
Origin 'null'错误。必须启动本地服务器（如 VS Code 的 Live Server 插件、npx serve、python3 -m http.server）。 -
引入第三方 CDN 模块失败：不是所有 CDN 都支持 CORS。例如：
<script type="module" src="https://libs.baidu.com/jquery/2.0.0/jquery.min.js"></script>会失败，因为百度静态资源站未开启 CORS；而https://unpkg.com/jquery@3.4.1/dist/jquery.min.js可以，因其响应头含Access-Control-Allow-Origin: *。 -
自建服务返回的 JS 模块被拦截：确保服务端对
.js（尤其是带type="module"的请求）响应中包含Access-Control-Allow-Origin，且值不为*时需与前端页面源完全匹配（如http://localhost:5173）。
二、路径与解析错误：404、Failed to load module、Unable to resolve
这类错误说明浏览器找到了入口 HTML，但无法定位或解析所声明的模块路径，常见于相对路径、构建配置或 import map 使用不当。
dmap-jsapi-skill
下载
DMap GL地图JSAPI（dmapgl）开发指南。用于编写、审查、调试 DMap 地图 API 代码，涵盖地图初始化、覆盖物渲染、图层管理、事件处理、控件交互等任务。当用户提及 dmap、dmapgl、jsapi‑gl 或相关地图开发需求时自动触发。
-
相对路径计算出错：ESM 中
import的路径是相对于当前模块 URL 的，不是 HTML 页面 URL。比如index.html引入./src/main.js，而main.js再import { foo } from '../utils/bar.js'，就要确认bar.js真实位置是否在src同级的utils目录下。 -
import map 中的 bare specifier 解析失败：例如
import React from 'react'，但 import map 里没定义"react"映射，或映射地址返回 404（可在 Network 面板检查该请求状态码和响应内容）。 -
构建后路径错位：Vite 或 Webpack 打包时若
base或publicPath配置与部署路径不一致（如部署到子路径/my-app/却未设base: '/my-app/'），会导致模块请求地址变成/assets/main.xxxx.js（404），实际应为/my-app/assets/main.xxxx.js。
三、调试建议：快速定位关键线索
别只看控制台第一行红字，重点看 Network 面板里失败请求的完整链路。
- 筛选
JS类型请求，找到状态码非 200 的条目，点开看Headers→Response Headers是否含Access-Control-Allow-Origin； - 查看
Preview或Response标签页，确认返回的是 JS 代码还是 404 HTML 页面； - 右键失败请求 → “Open in Sources”，看浏览器是否真把该模块加入 Sources 列表——没出现说明根本没加载成功；
- 用
curl -I或 Postman 请求模块 URL，验证服务端响应头和状态码，排除前端环境干扰。
四、ESM 特有的易忽略细节
有些行为看似正常，实则埋着隐患。
-
模块路径必须带扩展名：ESM 不支持自动补
.js，import './utils'会失败，必须写import './utils.js'（除非用 import map 或构建工具处理）； -
顶层 await 是合法的，但仅限模块作用域：不能在普通脚本（
type="text/javascript"）中使用，否则 SyntaxError； -
动态 import() 返回 Promise，但路径也受 CORS 和路径规则约束：错误不会立即抛出，需用
catch捕获，且同样要检查 Network 中对应请求。
