如何在Laravel Vite项目中从本地NPM包导入Mermaid JS？

前提确认 #

先确保已经通过NPM安装了Mermaid：

npm install mermaid --save-dev

方案1：通过打包工具（Vite/Laravel Mix）全局注入（推荐） #

如果用的是Laravel这类带打包工具的框架，直接在全局JS文件里配置即可：

1. 打开resources/js/app.js，添加以下代码：

import mermaid from 'mermaid';
// 挂载到window对象，实现全局可用
window.mermaid = mermaid;
// 初始化Mermaid
mermaid.initialize({ startOnLoad: true });

2. 运行打包命令：

# 开发环境
npm run dev
# 生产环境
npm run build

3. 确保模板中加载了打包后的JS文件，比如在Blade布局里：

@vite(['resources/js/app.js'])

之后就不需要单独在页面里写@push的Mermaid导入脚本了。

方案2：直接引入本地模块文件（不推荐，仅临时场景用） #

如果不想通过打包工具，直接在页面中引入本地node_modules里的文件，但要注意路径正确性：

@push('scripts')
    <script type="module">
        // 注意路径要对应你本地node_modules里的实际文件位置
        import mermaid from '/node_modules/mermaid/dist/mermaid.esm.min.mjs';
        window.mermaid = mermaid;
        mermaid.initialize({ startOnLoad: true });
    </script>
@endpush

注意：这种方式需要确保web服务器能访问到node_modules目录，或者在打包工具中配置静态资源映射，否则会出现404错误。

常见失效原因排查 #

• 未使用打包工具直接用import mermaid from 'mermaid'：浏览器无法识别NPM包名，必须通过打包工具解析模块依赖，或者使用完整的文件路径。
• 文件路径错误：不同版本的Mermaid输出文件路径可能有差异，比如部分版本的ES模块文件是mermaid.esm.js而非mermaid.esm.min.mjs，去node_modules/mermaid/dist目录下确认实际文件名。
• 缺少type="module"：script标签必须声明type="module"，否则浏览器不支持ES模块语法。

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