不灭的焱

加密类型:SHA/AES/RSA下载Go
复合类型:切片(slice)、映射(map)、指针(pointer)、函数(function)、通道(channel)、接口(interface)、数组(array)、结构体(struct) Go类型+零值nil
引用类型:切片(slice)、映射(map)、指针(pointer)、函数(function)、通道(channel) Go引用

作者:AlbertWen  添加时间:2026-11-14 17:25:40  修改时间:2026-11-21 08:54:55  分类:05.AdminLTE和Layui  编辑

目录

你的目标是把 AdminLTE 4 改造成一套可长期维护、可扩展的后台管理系统前端基础框架,而不仅仅是把几个 HTML 页面复制到 GoFrame 项目里。

结合你之前确定的开发方向,我建议采用:

GoFrame + Go 原生 HTML 模板引擎 + Vite + AdminLTE 4 + jQuery + Tabulator + ECharts + Layui

不使用 Vue、React,不采用前后端分离,也不需要为了 AdminLTE 引入 Astro。

一、先明确 AdminLTE 4 在整个项目中的定位

AdminLTE 4 是基于 Bootstrap 5 的开源后台管理模板,采用原生 JavaScript / TypeScript 实现交互,不依赖 jQuery。它本质上提供的是管理后台的界面布局、样式和基础交互能力,而不是完整的后台业务开发框架。

1. 推荐技术分工

技术

负责什么

GoFrame

HTTP 路由、业务逻辑、数据库访问、权限、服务端渲染

GoFrame gview

HTML 模板、公共布局、菜单和页面内容

AdminLTE 4

顶部导航栏、侧边栏、主内容区、主题样式

Bootstrap 5

按钮、表单、Modal、Offcanvas、栅格布局

jQuery

DOM 操作、事件处理、Ajax

Tabulator

复杂业务表格、冻结列、排序、筛选、单元格选择

ECharts

数据看板、业务分析图表

Vite

前端依赖管理、JS/CSS 打包、代码分割、资源版本管理

这里有三个重要区别:

  • AdminLTE ≠ Bootstrap:AdminLTE 管理后台整体布局,Bootstrap 提供通用 UI 组件。
  • AdminLTE ≠ Tabulator:AdminLTE 提供表格的视觉环境,复杂表格功能由 Tabulator 实现。
  • Vite ≠ 前后端分离:Vite 只负责处理静态资源,HTML 仍由 GoFrame 服务器渲染。

2. 整体运行架构

例如浏览器访问 /crm/customers 时:

  1. GoFrame 路由接收请求并检查用户权限。
  2. Handler 查询页面所需的基础数据。
  3. gview 渲染 AdminLTE 的公共布局与 CRM 客户页面。
  4. 浏览器加载 Vite 构建的 CSS、JavaScript。
  5. Tabulator 通过 Ajax 请求 /api/crm/customers,展示客户列表。

这就实现了传统服务端 HTML 渲染和现代前端组件的结合。

二、AdminLTE 4 官方项目结构分析

官方资源:

我核对了官方仓库的源码入口、Astro 配置、SCSS 和 TypeScript 文件。当前 master 分支的 package.json 标示版本为 4.10.1,下面按这一版的工程组织方式分析。

2.1 官方源码目录

下面是精简后的重要结构,不是仓库全部文件:

AdminLTE/
├── src/
│   ├── html/                    # 官方演示页面源码
│   │   ├── components/          # Astro 公共组件
│   │   │   ├── _head.astro
│   │   │   ├── _scripts.astro
│   │   │   └── dashboard/
│   │   │       ├── _topbar.astro
│   │   │       ├── _sidenav.astro
│   │   │       └── _footer.astro
│   │   ├── pages/               # 演示页面
│   │   │   ├── index.astro
│   │   │   └── starter.astro
│   │   └── public/              # 演示站公共资源
│   │
│   ├── scss/                    # AdminLTE 样式源码
│   │   ├── adminlte.scss        # 主样式入口
│   │   ├── _variables.scss
│   │   ├── _variables-dark.scss
│   │   ├── _bootstrap-overrides.scss
│   │   └── parts/              # 布局与组件样式
│   │
│   ├── ts/                      # AdminLTE JS/TS 源码
│   │   ├── adminlte.ts          # JS 主入口
│   │   ├── layout.ts
│   │   ├── push-menu.ts
│   │   ├── treeview.ts
│   │   ├── card-widget.ts
│   │   ├── color-mode.ts
│   │   ├── sidebar-search.ts
│   │   └── ...
│   │
│   ├── assets/                  # 图像等资源
│   └── config/                  # 官方编译配置
│       ├── astro.config.mjs
│       ├── rollup.config.js
│       └── assets.config.mjs
│
├── dist/                        # 编译后的发布文件
│   ├── css/
│   │   ├── adminlte.css
│   │   └── adminlte.min.css
│   ├── js/
│   │   ├── adminlte.js
│   │   ├── adminlte.min.js
│   │   └── adminlte.esm.js
│   ├── assets/
│   └── ...
│
├── docs/                        # 文档相关文件
├── tests/                       # 测试
├── package.json
└── tsconfig.json

2.2 每个目录的用途

目录

作用

GoFrame 项目是否需要

src/html/

官方 Demo 页面、公共组件

参考结构,移植 HTML

src/scss/

AdminLTE 样式源码

深度主题定制时使用

src/ts/

侧边栏、卡片等交互逻辑

通常不必修改

src/assets/

Logo、图片等

按需引入

src/config/

AdminLTE 自身的构建配置

不需要复制

dist/css/

已编译 CSS

需要,通过 npm 引入

dist/js/

已编译 JS

需要,通过 npm 引入

docs/

官方文档

不需要

tests/

AdminLTE 自身测试

不需要

关键结论:不要把 AdminLTE 的整个 GitHub 仓库复制进 GoFrame 项目。

推荐通过 npm 安装 admin-lte,利用它的发布资源,在自己项目的 frontend/ 目录开发 JS、CSS,而 HTML 页面放到 GoFrame 的 resource/template/ 目录。

2.3 为什么官方会使用 Astro?

从官方配置可以看到:

export default defineConfig({
  output: "static",
  srcDir: "./src/html",
  publicDir: "./src/html/public",
  outDir: "./dist/html"
})

Astro 在这里主要用来组织和生成官方的静态演示页面。

例如:

src/html/pages/starter.astro

这个文件引入了:

import Head from "@components/_head.astro"
import Footer from "@components/dashboard/_footer.astro"
import Topbar from "@components/dashboard/_topbar.astro"
import Sidenav from "@components/dashboard/_sidenav.astro"
import Scripts from "@components/_scripts.astro"

这些 Astro 组件分别负责页面的 Head、顶部导航、侧边菜单、底部栏和 JS 引用。

迁移到 GoFrame 时,可以建立如下对应关系:

AdminLTE 官方文件

GoFrame 模板

_head.astro

layout/head.html

_topbar.astro

layout/header.html

_sidenav.astro

layout/sidebar.html

_footer.astro

layout/footer.html

_scripts.astro

通过 Vite 资源管理统一输出

starter.astro

layout/main.html + 业务页面模板

这样就不需要使用 Astro 编译 HTML。后续所有业务页面直接使用 GoFrame 的 gview 处理。

2.4 AdminLTE JavaScript 源码分析

以 src/ts/adminlte.ts 为例,官方将多个独立的插件汇总导出,随后由 Rollup 编译为 UMD 和 ESM 两种 JavaScript 资源。

模块

负责的功能

二次开发用途

Layout

主界面布局

页面布局控制

PushMenu

侧边栏展开和收起

菜单状态

Treeview

多级菜单展开

CRM/SRM 多级导航

CardWidget

卡片折叠、移除、最大化

统计看板

FullScreen

页面全屏

大屏看板

ColorMode

明暗模式切换

用户主题偏好

SidebarSearch

侧边菜单搜索

系统导航

DirectChat

聊天窗口交互

在线消息

Accessibility

无障碍辅助

可访问性

AdminLTE 自己的交互大多采用 data-lte-* 特性实现。例如:

<!-- 切换侧边栏 -->
<a href="#" data-lte-toggle="sidebar">
  <i class="bi bi-list"></i>
</a>

<!-- 折叠卡片 -->
<button type="button"
        data-lte-toggle="card-collapse">
  折叠
</button>

<!-- 最大化卡片 -->
<button type="button"
        data-lte-toggle="card-maximize">
  最大化
</button>

这些功能不需要再通过 jQuery 重写。

2.5 AdminLTE 样式源码分析

主入口为:

src/scss/adminlte.scss

它将 Bootstrap 样式、AdminLTE 变量及各功能组件样式整合起来。

因此,AdminLTE 4 的 CSS 已经包含其所需的 Bootstrap 样式部分,正常使用时不要再额外引入一份完整的 bootstrap.min.css,否则可能产生样式覆盖或体积重复问题。

二次开发可分为三个级别:

级别

修改方式

推荐场景

简单定制

新建自己的 app.css

字体、颜色、边距、表格样式

中度定制

自己的 CSS/SCSS 覆盖 Bootstrap 变量或样式

企业品牌主题

深度定制

通过 AdminLTE SCSS 源码重新编译

改侧边栏宽度、布局体系等

绝大多数业务系统,建议从独立的业务样式文件开始,不直接修改 AdminLTE 发布包源码。

三、AdminLTE 4 页面的核心 HTML 结构

理解这部分,是后续拆分 GoFrame 模板的基础。

对应的 HTML 结构:

<body class="layout-fixed sidebar-expand-lg bg-body-tertiary">

  <div class="app-wrapper">

    <!-- 顶部导航 -->
    <nav class="app-header navbar navbar-expand bg-body">
      ...
    </nav>

    <!-- 左侧菜单 -->
    <aside class="app-sidebar bg-body-secondary shadow">
      ...
    </aside>

    <!-- 内容区域 -->
    <main class="app-main">

      <!-- 页面标题 -->
      <div class="app-content-header">
        ...
      </div>

      <!-- 业务页面 -->
      <div class="app-content">
        <div class="container-fluid">
          ...
        </div>
      </div>

    </main>

    <!-- 底部栏 -->
    <footer class="app-footer">
      ...
    </footer>

  </div>

</body>

这五大区域是 AdminLTE 4 布局的基础。

迁移时,建议将 Header、Sidebar、Footer 抽成全局公共模板,把不同业务页面放进 app-content。

四、推荐的 GoFrame 工程目录结构

针对你的单体、多业务子系统项目,我建议把Go 后端代码、HTML 模板、前端工程源码、最终静态资源分开管理。

下面既适用于普通 GoFrame 项目,也方便后续采用 go.work 组织多个 Go 模块。

freight-system/
│
├── cmd/
│   └── server/
│       └── main.go
│
├── internal/
│   ├── router/                    # HTTP 路由
│   ├── middleware/                # 鉴权、日志等
│   └── ui/                        # UI公共能力
│       └── vite.go                # Vite资源管理
│
├── modules/                       # Go业务子系统
│   ├── crm/
│   ├── srm/
│   ├── pms/
│   ├── oms/
│   └── fns/
│
├── resource/
│   ├── template/                  # GoFrame HTML模板
│   │   ├── layout/
│   │   │   ├── main.html          # 后台主布局
│   │   │   ├── header.html        # 顶部导航
│   │   │   ├── sidebar.html       # 左侧菜单
│   │   │   └── footer.html        # 底部栏
│   │   │
│   │   ├── dashboard/
│   │   │   └── index.html
│   │   │
│   │   ├── crm/
│   │   │   ├── customer/
│   │   │   │   ├── index.html
│   │   │   │   └── form.html
│   │   │   └── lead/
│   │   │       └── index.html
│   │   │
│   │   ├── srm/
│   │   ├── pms/
│   │   ├── oms/
│   │   └── fns/
│   │
│   └── public/                    # GoFrame静态文件根目录
│       ├── assets/                # Vite输出目录(自动生成)
│       │   ├── .vite/
│       │   │   └── manifest.json
│       │   └── static/
│       ├── uploads/               # 示例:上传文件(需单独访问控制)
│       ├── images/                # 不需编译打包的业务图片
│       └── favicon.ico 
│
├── frontend/                       # 独立前端构建工程
│   ├── src/
│   │   ├── entries/
│   │   │   ├── app.js             # 全站公共入口
│   │   │   ├── crm/
│   │   │   │   ├── customer.js
│   │   │   │   └── lead.js
│   │   │   ├── srm/
│   │   │   ├── pms/
│   │   │   ├── oms/
│   │   │   └── fns/
│   │   │
│   │   ├── components/             # 自己开发的公共组件
│   │   │   ├── table.js
│   │   │   ├── modal.js
│   │   │   └── request.js
│   │   │
│   │   └── styles/
│   │       └── app.css            # 自定义主题及业务样式
│   │
│   ├── vite.config.js
│   ├── package.json
│   └── node_modules/              # npm自动生成
│
├── manifest/
│   └── config/
│       └── config.yaml
│
├── go.mod
└── go.work                         # 可选,多Go模块时使用

这里有四条建议:

第一:模板按业务子系统划分。 CRM 的 HTML 放在 resource/template/crm/,SRM 的 HTML 放在 resource/template/srm/。

第二:前端 JS 按业务子系统划分。 CRM 客户管理 JS 放在 frontend/src/entries/crm/customer.js,避免所有业务 JS 混在一个文件中。

第三:公共布局只保留一份。 整个系统共享 AdminLTE Header、Sidebar、Footer、主题等基础设施。

第四:前端源码与编译结果分离。 frontend/src/ 是维护代码的地方,resource/public/assets/ 是发布资源,不应直接编辑打包文件。

如果你的 CRM、SRM 等是独立的 go.mod 子模块,也不用强制给每个 Go 模块再单独配置一个 Vite。可以由主应用集中管理页面模板、公共资源和前端构建。

五、实战:把 AdminLTE 4 集成到 GoFrame

下面构建一个最小的 CRM 客户管理页面。

目标是实现:

  • 访问 /crm/customers,返回 AdminLTE 4 管理页面。

  • 页面由 GoFrame 模板引擎渲染。

  • 左侧 CRM 菜单自动展开。

  • 通过 Tabulator 展示客户表格。

  • 使用 Ajax 请求 GoFrame API 获取客户数据。

  • CSS/JS 由 Vite 管理和打包。

5.1 安装 AdminLTE 4 和相关依赖

先在 GoFrame 项目根目录下创建前端工程。

mkdir -p frontend
cd frontend

npm init -y

# 后台布局和基础UI
npm install admin-lte@4.10.1 bootstrap@5.3.8
npm install bootstrap-icons overlayscrollbars jquery

# 复杂表格和图表
npm install tabulator-tables echarts

# Layui组件库
npm install layui

# 前端构建工具
npm install -D vite

这里明确指定了 AdminLTE 的版本,以避免官方升级影响项目。

在 frontend/package.json 中配置脚本:

{
  "type": "module",
  "scripts": {
    "dev": "vite --host 127.0.0.1",
    "build": "vite build",
    "preview": "vite preview"
  }
}

这是需要添加或合并的字段,不是覆盖 npm 生成的完整 package.json,已有的 dependencies、devDependencies 需要保留。

5.2 编写 Vite 配置

文件:frontend/vite.config.js

import { defineConfig } from "vite"
import { resolve } from "node:path"

export default defineConfig({
  // 生产环境静态资源URL前缀
  base: "/assets/",

  server: {
    host: "127.0.0.1",
    port: 5173,
    strictPort: true,
    origin: "http://localhost:5173",
    cors: {
      origin: "http://localhost:8000"
    }
  },

  build: {
    outDir: "../resource/public/assets",
    emptyOutDir: true,

    // 生成资源清单,供GoFrame读取
    manifest: true,

    // 编译后的JS/CSS等文件放在static中
    assetsDir: "static",

    rolldownOptions: {
      input: {
        app: resolve(import.meta.dirname, "src/entries/app.js"),

        crmCustomer: resolve(
          import.meta.dirname,
          "src/entries/crm/customer.js"
        )

        // 后续增加新的业务入口
      }
    }
  }
})

这里采用的是当前 Vite 的多入口资源构建方式。Vite 官方也专门提供了服务端模板引擎集成指南,支持使用 Manifest 将前端构建结果交给后端渲染。

rolldownOptions.input 的作用,就是告诉 Vite 哪些 JS 是独立入口。

例如以后增加:

input: {
  app: resolve(import.meta.dirname, "src/entries/app.js"),
  crmCustomer: resolve(import.meta.dirname, "src/entries/crm/customer.js"),
  crmLead: resolve(import.meta.dirname, "src/entries/crm/lead.js"),
  srmSupplier: resolve(import.meta.dirname, "src/entries/srm/supplier.js"),
  pmsProduct: resolve(import.meta.dirname, "src/entries/pms/product.js")
}

每个页面只需要引入自己的入口文件以及公共入口文件,不需要加载所有业务模块的代码。

5.3 编写全局公共入口

文件:frontend/src/entries/app.js

// 1. 公共CSS
import "bootstrap-icons/font/bootstrap-icons.css"
import "overlayscrollbars/styles/overlayscrollbars.css"
import "admin-lte/dist/css/adminlte.min.css"

// 2. 自定义CSS(在AdminLTE之后)
import "../styles/app.css"

// 3. JS依赖
import $ from "jquery"
import "bootstrap"
import "admin-lte"

import { OverlayScrollbars } from "overlayscrollbars"

// 4. 供传统非模块脚本使用
window.$ = $
window.jQuery = $

// 5. 初始化公共页面组件
document.addEventListener("DOMContentLoaded", () => {
  const sidebar = document.querySelector(".sidebar-wrapper")

  if (sidebar && window.innerWidth > 992) {
    OverlayScrollbars(sidebar, {
      scrollbars: {
        theme: "os-theme-light",
        autoHide: "leave",
        clickScroll: true
      }
    })
  }
})

注意:

  • AdminLTE 4 自身不需要 jQuery。
  • bootstrap 引入的是 Bootstrap JavaScript,样式已由 AdminLTE 提供。
  • 如果需要支持旧版依赖全局 $ 的插件,可以通过 window.jQuery 提供。
  • 对于有加载顺序要求的旧版 jQuery 插件,使用显式导入或按需 import(),不要仅依赖两个独立入口的执行先后。
  • OverlayScrollbars 是可选的滚动条增强功能。

AdminLTE 官方演示项目也使用 .sidebar-wrapper 初始化 OverlayScrollbars,但这部分不是 AdminLTE 主包自动提供的。

5.4 编写自定义样式

文件:frontend/src/styles/app.css

/* 应用级样式变量 */
:root {
  --app-content-padding: 1rem;
}

/* 业务页面内容边距 */
.app-content {
  padding-bottom: var(--app-content-padding);
}

/* 业务卡片 */
.app-main .card {
  border-radius: 6px;
}

/* 表格区域 */
.app-table {
  width: 100%;
  min-height: 300px;
}

/* 表格操作栏 */
.app-toolbar {
  display: flex;
  align-items: center;
  gap: 10px;
  flex-wrap: wrap;
}

/* 数据较多的页面 */
.app-page-full {
  min-width: 0;
}

/* 响应式 */
@media (max-width: 768px) {
  .app-toolbar {
    align-items: stretch;
  }
}

以后 CRM、SRM、OMS 的自定义 CSS,也可以放到各自模块中,避免公共样式文件过于庞大。

六、GoFrame 模板引擎集成

6.1 主布局模板 main.html

GoFrame 的 gview 支持 define/template 和 include 两种布局方式。其中 include 还可以接收变量形式的模板文件名,因此适合这种公共布局加业务内容的项目。

文件:resource/template/layout/main.html

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <meta name="viewport"
        content="width=device-width, initial-scale=1.0">

  <title>{{.Title}} - 货代业务管理系统</title>

  <!-- 读取AdminLTE保存的主题,避免闪屏 -->
  <script>
    (() => {
      try {
        const selected = localStorage.getItem("lte-theme")
        const dark = selected === "dark" ||
          (selected !== "light" &&
           matchMedia("(prefers-color-scheme: dark)").matches)

        document.documentElement.setAttribute(
          "data-bs-theme",
          dark ? "dark" : "light"
        )
      } catch (_) {
        document.documentElement.setAttribute(
          "data-bs-theme", "light"
        )
      }
    })()
  </script>

  <!-- Vite CSS -->
  {{.AssetsCSS}}
</head>

<body class="layout-fixed sidebar-expand-lg bg-body-tertiary">

  <div class="app-wrapper">

    {{include "layout/header.html" .}}

    {{include "layout/sidebar.html" .}}

    <main class="app-main">

      <div class="app-content-header">
        <div class="container-fluid">
          <h1 class="mb-0 fs-3">{{.Title}}</h1>
        </div>
      </div>

      <div class="app-content">
        <div class="container-fluid">

          <!-- 由GoFrame动态选择业务模板 -->
          {{include .PageTpl .}}

        </div>
      </div>

    </main>

    {{include "layout/footer.html" .}}

  </div>

  <!-- Vite JavaScript -->
  {{.AssetsJS}}

</body>
</html>

重点是这一句:

{{include .PageTpl .}}

假设 Handler 传入:

"PageTpl": "crm/customer/index.html"

那么 GoFrame 会将客户管理页面渲染到主内容区。

换一个业务页面时,只需要修改 PageTpl,而不是复制整套 AdminLTE 布局。

安全提醒: PageTpl 必须由服务端代码根据已注册路由决定,不能直接使用浏览器传入的模板路径。

另外,.AssetsCSS 和 .AssetsJS 需要由后端可信的资源管理代码产生,而不是从用户请求中读取 HTML 字符串。

6.2 顶部导航模板

文件:resource/template/layout/header.html

<nav class="app-header navbar navbar-expand bg-body">
  <div class="container-fluid">

    <ul class="navbar-nav">
      <li class="nav-item">
        <a class="nav-link"
           href="#"
           data-lte-toggle="sidebar"
           aria-label="切换菜单">
          <i class="bi bi-list"></i>
        </a>
      </li>

      <li class="nav-item d-none d-md-block">
        <a href="/dashboard" class="nav-link">
          工作台
        </a>
      </li>
    </ul>

    <ul class="navbar-nav ms-auto">
      <li class="nav-item dropdown">
        <a class="nav-link dropdown-toggle"
           href="#"
           data-bs-toggle="dropdown">
          <i class="bi bi-person-circle"></i>
          <span class="ms-1">{{.UserName}}</span>
        </a>

        <ul class="dropdown-menu dropdown-menu-end">
          <li>
            <a href="/profile" class="dropdown-item">
              个人中心
            </a>
          </li>
          <li><hr class="dropdown-divider"></li>
          <li>
            <a href="/logout" class="dropdown-item">
              退出登录
            </a>
          </li>
        </ul>
      </li>
    </ul>

  </div>
</nav>

这里展示的是布局示例,/dashboard、/profile 和 /logout 需要在你的实际项目中分别实现;退出登录应采用有 CSRF 防护的 POST 请求,而不应直接用 GET 修改会话状态。

6.3 左侧菜单模板

文件:resource/template/layout/sidebar.html

<aside class="app-sidebar bg-body-secondary shadow"
       data-bs-theme="dark"
       data-enable-persistence="true">

  <div class="sidebar-brand">
    <a href="/dashboard" class="brand-link">
      <span class="brand-text fw-light">
        Freight System
      </span>
    </a>
  </div>

  <div class="sidebar-wrapper">
    <nav class="mt-2">

      <ul class="nav sidebar-menu flex-column"
          data-lte-toggle="treeview"
          data-accordion="false"
          role="navigation"
          aria-label="主菜单">

        <!-- 工作台 -->
        <li class="nav-item">
          <a href="/dashboard" class="nav-link">
            <i class="nav-icon bi bi-speedometer2"></i>
            <p>工作台</p>
          </a>
        </li>

        <!-- CRM -->
        <li class="nav-item
          {{if eq .ActiveModule "crm"}}menu-open{{end}}">

          <a href="#" class="nav-link
            {{if eq .ActiveModule "crm"}}active{{end}}">
            <i class="nav-icon bi bi-people"></i>
            <p>
              CRM 客户管理
              <i class="nav-arrow bi bi-chevron-right"></i>
            </p>
          </a>

          <ul class="nav nav-treeview">
            <li class="nav-item">
              <a href="/crm/customers" class="nav-link
                {{if eq .ActiveMenu "crm-customers"}}active{{end}}">
                <i class="nav-icon bi bi-circle"></i>
                <p>客户列表</p>
              </a>
            </li>

            <li class="nav-item">
              <a href="/crm/leads" class="nav-link">
                <i class="nav-icon bi bi-circle"></i>
                <p>销售线索</p>
              </a>
            </li>
          </ul>
        </li>

        <!-- SRM -->
        <li class="nav-item">
          <a href="/srm/suppliers" class="nav-link">
            <i class="nav-icon bi bi-truck"></i>
            <p>SRM 供应商管理</p>
          </a>
        </li>

        <!-- PMS -->
        <li class="nav-item">
          <a href="/pms/products" class="nav-link">
            <i class="nav-icon bi bi-box-seam"></i>
            <p>PMS 产品管理</p>
          </a>
        </li>

      </ul>
    </nav>
  </div>
</aside>

其中:

{{if eq .ActiveModule "crm"}}menu-open{{end}}

表示当前位于 CRM 子系统时,自动展开 CRM 菜单。

{{if eq .ActiveMenu "crm-customers"}}active{{end}}

表示当前是客户列表页面时,选中该子菜单。

menu-open、active、nav-treeview 等配合 AdminLTE 的 Treeview 组件使用即可。

GitHub

这里的菜单只是示例。正式项目应该通过后端菜单配置和权限过滤生成,避免每次增加新系统都必须修改一大段 HTML。

6.4 底部栏

文件:resource/template/layout/footer.html

<footer class="app-footer">
  <div class="float-end d-none d-sm-inline">
    v1.0.0
  </div>
  <strong>Freight System</strong>
  &copy; 2026
</footer>

到这里,AdminLTE 的公共 HTML 布局就已经迁移到 GoFrame 了。

七、实战:CRM 客户管理页面

7.1 客户列表 HTML

文件:resource/template/crm/customer/index.html

这里只写业务内容,不再包含 <html>、<head>、<body> 或公共菜单。

<div class="card">

  <div class="card-header">
    <div class="app-toolbar">

      <input type="search"
             id="customer-keyword"
             class="form-control form-control-sm"
             style="width:220px"
             placeholder="客户名称/联系人">

      <button type="button"
              id="btn-search"
              class="btn btn-sm btn-primary">
        <i class="bi bi-search"></i>
        查询
      </button>

      <button type="button"
              id="btn-reset"
              class="btn btn-sm btn-outline-secondary">
        重置
      </button>

      <button type="button"
              class="btn btn-sm btn-success ms-auto"
              data-bs-toggle="modal"
              data-bs-target="#customer-modal">
        <i class="bi bi-plus-lg"></i>
        新增客户
      </button>

    </div>
  </div>

  <div class="card-body">
    <div id="customer-table" class="app-table"></div>
  </div>

</div>

<!-- 新增客户弹窗 -->
<div class="modal fade"
     id="customer-modal"
     tabindex="-1"
     aria-labelledby="customer-modal-title"
     aria-hidden="true">

  <div class="modal-dialog modal-lg">
    <div class="modal-content">

      <div class="modal-header">
        <h5 class="modal-title"
            id="customer-modal-title">新增客户</h5>

        <button type="button"
                class="btn-close"
                data-bs-dismiss="modal"
                aria-label="关闭"></button>
      </div>

      <div class="modal-body">
        <div class="mb-3">
          <label for="customer-name"
                 class="form-label">客户名称</label>
          <input id="customer-name"
                 class="form-control"
                 name="name">
        </div>
      </div>

      <div class="modal-footer">
        <button type="button"
                class="btn btn-secondary"
                data-bs-dismiss="modal">
          取消
        </button>

        <button type="button"
                class="btn btn-primary"
                id="btn-save-customer">
          保存
        </button>
      </div>

    </div>
  </div>
</div>

这个页面已经结合了 AdminLTE 卡片、Bootstrap Modal、Bootstrap 表单和预留的 Tabulator 表格区域。

7.2 客户列表 JavaScript

文件:frontend/src/entries/crm/customer.js

import $ from "jquery"
import { TabulatorFull as Tabulator } from "tabulator-tables"

import "tabulator-tables/dist/css/tabulator.min.css"

// 初始化客户表格
const table = new Tabulator("#customer-table", {
  height: "550px",
  layout: "fitColumns",

  // 服务端分页
  pagination: true,
  paginationMode: "remote",
  paginationSize: 20,

  // GoFrame API
  ajaxURL: "/api/crm/customers",
  ajaxParams: {
    keyword: ""
  },

  placeholder: "暂无客户数据",

  columns: [
    {
      title: "客户ID",
      field: "id",
      width: 100
    },
    {
      title: "客户名称",
      field: "name",
      minWidth: 180
    },
    {
      title: "联系人",
      field: "contact",
      width: 130
    },
    {
      title: "联系电话",
      field: "phone",
      width: 150
    },
    {
      title: "客户类型",
      field: "type",
      width: 130
    }
  ]
})

// 查询
$("#btn-search").on("click", () => {
  const keyword = $("#customer-keyword").val().trim()

  table.setData("/api/crm/customers", {
    keyword
  })
})

// 重置
$("#btn-reset").on("click", () => {
  $("#customer-keyword").val("")

  table.setData("/api/crm/customers", {
    keyword: ""
  })
})

// 新增客户示例:仅演示交互
$("#btn-save-customer").on("click", () => {
  const name = $("#customer-name").val().trim()

  if (!name) {
    alert("请输入客户名称")
    return
  }

  // 实际项目应调用POST接口完成保存,
  // 成功后关闭弹窗并刷新表格
  alert(`待提交客户:${name}`)
})

Tabulator 支持远程分页,并约定由后端返回分页数据和总页数。

Tabulator

这里使用 jQuery 处理按钮事件,Tabulator 负责表格。彼此没有冲突,也不需要实现 Vue 组件。

正式项目中,查询条件、分页、排序和筛选应统一封装为表格公共组件,并对应后端的统一查询协议。

八、GoFrame 后端如何渲染页面和返回 API

8.1 Vite Manifest 资源管理

这是整个集成方案中比较重要的一步。

Vite 生产构建后,文件名通常包含 Hash,例如:

resource/public/assets/
├── .vite/
│   └── manifest.json
└── static/
    ├── app-abc123.js
    ├── app-def456.css
    ├── customer-ghi789.js
    └── customer-jkl012.css

这些文件名只是示例,真实文件名由构建产生。

因此不能在 GoFrame 模板中写死:

<script src="/assets/static/app-abc123.js"></script>

应该由后端解析 Vite 生成的 manifest.json。

文件:internal/ui/vite.go

package ui

import (
    "encoding/json"
    "fmt"
    "html/template"
    "os"
    "strings"
)

type manifestEntry struct {
    File    string   `json:"file"`
    CSS     []string `json:"css"`
    Imports []string `json:"imports"`
}

// Tags 返回页面所需的CSS和JS标签。
// entries传入Vite入口文件的相对路径。
func Tags(entries ...string) (template.HTML, template.HTML, error) {
    var css strings.Builder
    var js strings.Builder

    // 开发环境:使用Vite Dev Server。
    if os.Getenv("APP_ENV") != "production" {
        js.WriteString(
            `<script type="module" src="http://localhost:5173/@vite/client"></script>` + "\n",
        )

        for _, entry := range entries {
            fmt.Fprintf(
                &js,
                "<script type=\"module\" src=\"http://localhost:5173/%s\"></script>\n",
                entry,
            )
        }

        return "", template.HTML(js.String()), nil
    }

    // 生产环境:读取Vite资源清单。
    data, err := os.ReadFile(
        "resource/public/assets/.vite/manifest.json",
    )
    if err != nil {
        return "", "", err
    }

    manifest := make(map[string]manifestEntry)

    if err = json.Unmarshal(data, &manifest); err != nil {
        return "", "", err
    }

    visited := make(map[string]bool)
    seenCSS := make(map[string]bool)
    cssFiles := make([]string, 0)

    // 递归收集入口及其依赖模块的CSS。
    var visit func(string) error

    visit = func(name string) error {
        if visited[name] {
            return nil
        }

        item, ok := manifest[name]
        if !ok {
            return fmt.Errorf("Vite entry not found: %s", name)
        }

        visited[name] = true

        for _, dep := range item.Imports {
            if err := visit(dep); err != nil {
                return err
            }
        }

        for _, file := range item.CSS {
            if !seenCSS[file] {
                seenCSS[file] = true
                cssFiles = append(cssFiles, file)
            }
        }

        return nil
    }

    for _, entry := range entries {
        if err := visit(entry); err != nil {
            return "", "", err
        }
    }

    for _, file := range cssFiles {
        fmt.Fprintf(
            &css,
            "<link rel=\"stylesheet\" href=\"/assets/%s\">\n",
            file,
        )
    }

    for _, entry := range entries {
        item := manifest[entry]

        fmt.Fprintf(
            &js,
            "<script type=\"module\" src=\"/assets/%s\"></script>\n",
            item.File,
        )
    }

    return template.HTML(css.String()),
        template.HTML(js.String()),
        nil
}

这是一个可用于集成的基础实现。它实现了:

  1. 开发模式读取 Vite Dev Server。
  2. 生产模式读取 Manifest。
  3. 多入口 JS 加载。
  4. 递归收集依赖 CSS。
  5. CSS 去重。
  6. 自动适配构建文件的 Hash 名称。

上面的 template.HTML 只应包装本地受信任构建清单生成的标签;入口名称必须在后端代码中固定,不接受用户输入。正式上线时还可以增加 Manifest 缓存、路径校验、模块预加载、CSP 等处理。

8.2 GoFrame 的 Handler

假设项目 Go module 名称为:

example.com/freight-system

在 GoFrame 项目中引入 UI 模块:

package main

import (
    "github.com/gogf/gf/v2/frame/g"
    "github.com/gogf/gf/v2/net/ghttp"

    "example.com/freight-system/internal/ui"
)

func main() {
    // HTML模板目录
    g.View().SetPath("resource/template")

    s := g.Server()
    s.SetPort(8000)

    // 静态文件目录
    s.SetServerRoot("resource/public")

    // CRM客户页面
    s.BindHandler("/crm/customers", func(r *ghttp.Request) {

        css, js, err := ui.Tags(
            "src/entries/app.js",
            "src/entries/crm/customer.js",
        )

        if err != nil {
            r.Response.WriteStatus(500, "资源加载失败")
            return
        }

        err = r.Response.WriteTpl("layout/main.html", g.Map{
            "Title":        "客户管理",
            "UserName":     "管理员",
            "ActiveModule": "crm",
            "ActiveMenu":   "crm-customers",
            "PageTpl":      "crm/customer/index.html",
            "AssetsCSS":    css,
            "AssetsJS":     js,
        })

        if err != nil {
            r.Response.WriteStatus(500, "页面渲染失败")
            return
        }
    })

    // CRM客户数据接口(模拟数据)
    s.BindHandler("/api/crm/customers", func(r *ghttp.Request) {

        customers := []g.Map{
            {
                "id":      1,
                "name":    "ABC Logistics",
                "contact": "Tom",
                "phone":   "13800000001",
                "type":    "国内同行",
            },
            {
                "id":      2,
                "name":    "XYZ Cargo",
                "contact": "Jack",
                "phone":   "13800000002",
                "type":    "海外同行",
            },
            {
                "id":      3,
                "name":    "Global Shipping",
                "contact": "Lucy",
                "phone":   "13800000003",
                "type":    "国内直客",
            },
        }

        page := r.GetQuery("page", 1).Int()
        size := r.GetQuery("size", 20).Int()

        if page < 1 {
            page = 1
        }
        if size < 1 || size > 100 {
            size = 20
        }

        total := len(customers)
        lastPage := (total + size - 1) / size

        start := (page - 1) * size
        if start > total {
            start = total
        }

        end := start + size
        if end > total {
            end = total
        }

        _ = r.Response.WriteJson(g.Map{
            "last_page": lastPage,
            "data":      customers[start:end],
        })
    })

    s.Run()
}

需要注意:这个 Handler 是页面集成演示,用模拟数据展示渲染和分页协议,还没有接入数据库、登录鉴权、客户新增保存或实际搜索过滤。

正式项目应将这些路由注册到对应的 modules/crm 中,并在业务服务层完成分页、过滤和权限校验。

GoFrame 官方确认支持 SetServerRoot 静态文件配置和 Response.WriteTpl() 模板输出。

8.3 前后端如何关联

URL

GoFrame 处理

前端处理

/crm/customers

输出 HTML 模板

AdminLTE 绘制布局

/api/crm/customers

输出 JSON 数据

Tabulator 展示数据

/assets/static/xxx.js

返回打包文件

浏览器执行 JS

/assets/static/xxx.css

返回打包文件

浏览器应用样式

这样的模式与前后端分离不同:HTML 仍然由 GoFrame 生成,只是具体表格通过 Ajax 异步加载。

8.4 启动和调试

首次创建 Go 项目时,在项目根目录执行:

go mod init example.com/freight-system
go get github.com/gogf/gf/v2@latest

如果已有 GoFrame 项目则无需重复初始化。

终端一:启动 Vite

cd frontend
npm run dev

终端二:启动 GoFrame

go run ./cmd/server

然后访问:

http://localhost:8000/crm/customers

此时:

  • GoFrame 在 8000 端口提供页面和 API。

  • Vite 在 5173 端口提供开发版 JS/CSS。

  • 修改 JS/CSS 可以通过 Vite 实现热更新。

  • 修改 GoFrame HTML 模板,刷新浏览器即可查看修改后的页面。

上述命令以项目根目录为工作目录,且假定 GoFrame 入口位于 cmd/server。

注意:这是参考实现代码,未在你的实际 GoFrame 工程中编译运行。 复制时需要根据真实 module 路径、路由组织和部署目录调整。

九、二次开发:哪些功能应该封装成自己的公共组件?

完成基础集成后,真正重要的是二次开发的工程化。

我不建议业务人员直接操作 AdminLTE 源码,而是建立一层自己的 UI 公共组件体系。

9.1 推荐的二次开发范围

功能

基础依赖

二次开发建议

顶部导航栏

AdminLTE

用户信息、消息通知、全局搜索

侧边栏

AdminLTE Treeview

动态菜单、权限控制、当前菜单定位

Tab 页面

自行开发

多页面标签、切换、关闭、刷新

弹窗

Bootstrap Modal

统一打开、关闭、Ajax 加载

确认提示

SweetAlert2

删除确认、操作结果

表格

Tabulator

分页、筛选、列配置、导出

表单

Bootstrap

验证、数据回填、表单提交

图片上传

自选上传组件

拖拽上传、预览、大小限制

数据看板

ECharts

统一主题、图表刷新、响应式

主题

AdminLTE ColorMode

明暗模式、品牌定制

其中多标签页管理、权限菜单和复杂表格配置,应当作为你自己的业务平台能力开发,而不是修改 AdminLTE 核心文件来实现。

9.2 动态菜单与权限

前面给出的 sidebar.html 是静态菜单版本。

正式项目中,我建议菜单配置从后端生成。

例如后端构造:

menus := []g.Map{
    {
        "Name": "CRM客户管理",
        "Code": "crm",
        "Icon": "bi bi-people",
        "Children": []g.Map{
            {
                "Name": "客户列表",
                "Path": "/crm/customers",
                "Code": "crm-customers",
            },
            {
                "Name": "销售线索",
                "Path": "/crm/leads",
                "Code": "crm-leads",
            },
        },
    },
}

接下来由统一菜单服务完成权限过滤、菜单排序、菜单展开状态的计算,最后传递给 sidebar.html。

这里尤其需要注意:前端菜单隐藏不等于用户没有权限。 GoFrame 路由和 API 仍然必须进行后端权限校验。

9.3 公共 Ajax 弹窗

例如客户列表点击“编辑客户”,想从 GoFrame 加载一个 HTML 表单并显示在弹窗里。

你可以统一封装:

import { Modal } from "bootstrap"

export async function openHtmlModal(url) {
  const modalElement = document.getElementById("app-modal")
  const body = modalElement.querySelector(".modal-body")

  const response = await fetch(url, {
    credentials: "same-origin"
  })

  if (!response.ok) {
    throw new Error(`加载表单失败:${response.status}`)
  }

  body.innerHTML = await response.text()

  Modal.getOrCreateInstance(modalElement).show()
}

公共布局中提前声明 #app-modal,然后调用:

openHtmlModal("/crm/customers/1/edit")

注意,加载的是本系统受信任且经过服务端正确转义的 HTML 局部模板,不应把不可信内容直接写入 innerHTML。弹窗中的表单事件建议通过事件委托绑定,避免重复加载出现事件失效。

这也和你之前关注的 SweetAlert2 加载 Ajax HTML 有所区别:

  • Bootstrap Modal:适合较复杂的客户编辑、订单操作、业务表单。

  • SweetAlert2:适合删除确认、简单输入、成功失败提示。

9.4 AdminLTE 和 Tabulator 的结合

Tabulator 有自己独立的表格样式和交互逻辑,AdminLTE 不会替它提供列冻结、列拖动等功能。

建议建立 frontend/src/components/table.js,统一处理:

  • API 地址与查询参数。
  • 远程分页、排序与过滤。
  • 字段显隐与列顺序。
  • 冻结列、单元格复制。
  • 表格加载状态、错误提示。
  • 用户个人列配置的持久化。

业务模块只负责声明字段、操作按钮和数据接口。这样 CRM、SRM、OMS 才不会出现三套不同的表格实现。

9.5 主题和品牌样式

可以在 app.css 中对 AdminLTE 进行样式覆盖:

/* 业务系统自定义样式 */
.app-sidebar {
  --lte-sidebar-width: 260px;
}

.sidebar-brand .brand-text {
  font-weight: 600 !important;
}

.app-content .card {
  box-shadow: 0 1px 4px rgba(0, 0, 0, .06);
}

注意,部分布局变量在 AdminLTE SCSS 编译期使用。对于侧边栏宽度这类布局参数,简单 CSS 覆盖未必能同步更新所有布局计算,深度调整应通过官方 SCSS 重新编译。

HTML · AdminLTE Docs

十、生产环境编译与部署

开发阶段不需要生成静态资源,通过 Vite Dev Server 加载即可。

正式上线时执行:

cd frontend

# 安装锁定版本的依赖
npm ci

# 构建生产资源
npm run build

然后回到 GoFrame 项目根目录:

APP_ENV=production go run ./cmd/server

也可以先把 Go 程序编译为二进制,再进行部署。

生产环境发布时应包含:

server                       # Go编译后的程序
resource/
├── template/                # 所有HTML模板
└── public/
    ├── assets/              # Vite构建文件及Manifest
    └── images/
manifest/
└── config/                  # 必要配置

不需要上传 frontend/node_modules/ 或 AdminLTE 官方的 Astro 源码。

部署注意事项: 当前示例使用相对路径读取模板和 Manifest,因此服务进程工作目录应为项目发布根目录,或者在正式项目中改成明确的绝对路径。生产 Web 服务器还应限制外部访问 .vite/ 等构建元数据目录,并配置静态资源缓存策略。

十一、二次开发时最容易踩的坑

问题

原因

处理方式

侧边栏按钮无效

未加载 AdminLTE JS 或 HTML 结构错误

检查 data-lte-toggle

多级菜单不展开

缺少 Treeview 结构或状态类

检查 nav-treeview、menu-open

Bootstrap 弹窗无效

未加载 Bootstrap JS

检查 JS 入口

jQuery 插件报错

jQuery 未正确加载或初始化顺序错误

明确导入依赖

CSS 样式冲突

重复引入 Bootstrap CSS

避免重复引入

页面 CSS 不生效

没有包含当前入口的 Manifest CSS

检查资源管理代码

Vite 开发正常,生产白屏

文件 Hash、资源路径或 Manifest 错误

检查 base、outDir

页面出现 {{ }} 解析问题

GoFrame 模板与其他模板语法冲突

将复杂 JS 放到独立文件

动态 HTML 中按钮失效

局部替换后事件未正确绑定

使用事件委托

Dark Mode 下表格颜色不统一

第三方组件未同步主题

给 Tabulator 配置暗色样式

还有一个重要的版本差异:AdminLTE 4 相比 AdminLTE 3 已经大幅调整了布局类名和交互 API。不要直接照搬 AdminLTE 3 的 data-widget、main-sidebar、content-wrapper 等旧版教程代码。

十二、最终开发方案

对于你的 GoFrame 货代业务系统,我建议分阶段实施。

第一阶段:完成公共布局

实现 AdminLTE Header、Sidebar、Footer、主内容区、菜单展开、主题切换和 GoFrame 模板嵌套。

第二阶段:统一前端工程

引入 Vite,建立公共入口、业务入口、Manifest 管理、开发热更新与生产构建。

第三阶段:开发公共组件

优先封装 Tabulator、Ajax 请求、Bootstrap Modal、操作提示、权限控制和文件上传。

第四阶段:实现业务子系统

按 CRM、SRM、PMS、OMS、FNS 划分 HTML、JS 和业务模块,逐步开发和复用公共能力。

最终建议遵循一个原则:

AdminLTE 4 只负责后台界面的基础框架;GoFrame 负责服务端模板渲染和业务处理;Vite 负责静态资源管理;业务组件由自己的前端工程维护。

这样既保留了你希望使用的传统 GoFrame 模板开发方式,也不会牺牲现代前端在依赖管理、模块划分、资源打包和组件复用方面的能力。

 


 

上述的 .vite 目录干嘛用的,为啥要加个点. 呢?

在前面 GoFrame + Vite + AdminLTE 4 的项目结构中:

resource/public/assets/
├── .vite/
│   └── manifest.json
└── static/
    ├── app-abc123.js
    ├── app-def456.css
    └── customer-ghi789.js

这里的 .vite 是 Vite 构建工具默认用于存放构建元数据的目录,主要不是存放业务代码。

一、.vite 目录有什么用?

在我们之前的 Vite 配置中:

export default defineConfig({
  build: {
    outDir: "../resource/public/assets",
    manifest: true
  }
})

当执行:

npm run build

Vite 会生成:

assets/
├── .vite/
│   └── manifest.json
└── static/
    ├── app-abc123.js
    └── app-def456.css

其中 manifest.json 的作用是建立前端源码入口与编译后文件之间的映射关系。

例如:

{
  "src/entries/app.js": {
    "file": "static/app-abc123.js",
    "isEntry": true,
    "css": [
      "static/app-def456.css"
    ]
  }
}

因为 Vite 打包后的文件名称包含 Hash,每次修改代码,Hash 可能发生变化。

GoFrame 后端可以读取这个 Manifest,动态生成正确的资源地址,而不用把文件名写死在 HTML 模板中。

二、为什么目录名前面有个点 .?

这主要是一种 Unix/Linux 文件命名约定。

在 macOS、Linux 中,以 . 开头的文件或目录通常被视为隐藏文件或隐藏目录。

例如:

名称 用途
.git/ Git 仓库内部数据
.vscode/ VS Code 项目配置
.idea/ JetBrains IDE 项目配置
.github/ GitHub Actions 等仓库配置
.vite/ Vite 构建元数据

注意:点号并不代表文件被加密或受到访问保护,只是一种隐藏和命名约定。

在 macOS 中,可以使用:

ls -la

查看隐藏文件和目录。

Finder 中则可以按 Command + Shift + . 显示或隐藏这些文件。

三、.vite 目录名可以改吗?

可以。 Vite 允许自定义 Manifest 的输出路径。

例如:

build: {
  outDir: "../resource/public/assets",
  manifest: "manifest.json"
}

那么构建后会变成:

assets/
├── manifest.json
└── static/
    ├── app-abc123.js
    └── app-def456.css

如果你希望保持默认的 .vite/manifest.json,则继续使用:

manifest: true

需要注意:如果你修改了 Manifest 输出位置,那么之前 GoFrame 中读取文件的路径也必须一起调整。

四、.vite 与 node_modules/.vite 有什么区别?

这是两个容易混淆的目录。

目录 用途
node_modules/.vite/ Vite 开发服务器的依赖预构建缓存
dist/.vite/ 或 assets/.vite/ 生产构建输出的元数据,如 Manifest

前者通常用于加速开发,后者则可以帮助 GoFrame 正确引用生产环境的静态资源。

针对你的 GoFrame 项目,我建议保留 Vite 默认的 .vite/manifest.json 结构。 不需要为了去掉目录名前面的点号而修改配置,它是 Vite 的正常行为。更重要的是,不要把 .vite 当作访问控制机制;正式部署时应避免通过公网直接暴露 Manifest 文件。

Vite 官方文档也明确规定:build.manifest: true 时,生成路径就是 .vite/manifest.json。

一句话总结:

.vite 前面的点是隐藏目录的命名习惯;manifest.json 才是 GoFrame 集成 Vite 时真正需要读取的构建清单。

 


 

上述提到的 <script type="module" 的作用是啥?

<script type="module"> 是 HTML5 中用于加载 JavaScript ES Module(ES 模块,简称 ESM) 的方式。

在你的 GoFrame + Vite + AdminLTE 4 + jQuery 技术方案中,推荐使用 type="module" 加载 Vite 编译后的 JavaScript。

一、普通 script 和 type="module" 有什么区别?

1. 普通 JavaScript

传统方式:

<script src="/js/jquery.min.js"></script>
<script src="/js/bootstrap.min.js"></script>
<script src="/js/app.js"></script>

特点:

  • 默认按顺序加载和执行(未使用 async、defer 时)。
  • 经典脚本的顶层 var 和函数声明通常成为全局对象属性。
  • 不能直接使用静态 import、export 语法。
  • 默认可能阻塞 HTML 解析。

2. ES Module 方式

<script type="module" src="/dist/static/app-a1b2c3.js"></script>

特点:

  • 支持 import、export。
  • 每个模块拥有自己的作用域。
  • 自动延迟执行,不阻塞 HTML 解析。
  • 浏览器能够自动解析和加载模块依赖。
  • 默认使用严格模式。
  • 模块脚本支持按需动态加载。

二、import 和 export 是怎么工作的?

例如有三个 JS 文件:

frontend/src/
├── main.js
├── utils.js
└── customer.js

utils.js

export function formatMoney(amount) {
  return `¥${Number(amount).toFixed(2)}`
}

customer.js

import { formatMoney } from "./utils.js"

export function showCustomer() {
  console.log(formatMoney(1234.5))
}

main.js

import { showCustomer } from "./customer.js"

showCustomer()

HTML 只需要引入入口文件:

<script type="module" src="/src/main.js"></script>

浏览器会根据 import 关系自动加载依赖。

三、为什么 Vite 编译后还需要 type="module"?

你之前的代码:

// frontend/src/entries/app.js

import "admin-lte/dist/css/adminlte.min.css"
import "bootstrap-icons/font/bootstrap-icons.css"

import $ from "jquery"
import "bootstrap"
import "admin-lte"

window.$ = $
window.jQuery = $

通过 Vite 编译后会生成类似:

resource/public/dist/
├── static/
│   ├── app-a1b2c3.js
│   ├── app-d4e5f6.css
│   └── vendor-x1y2z3.js

生产环境 HTML:

<link rel="stylesheet" href="/dist/static/app-d4e5f6.css">

<script type="module" src="/dist/static/app-a1b2c3.js"></script>

为什么需要 type="module"?

因为 Vite 默认生成面向现代浏览器的 ES Module 格式,编译后的代码可能仍然包含模块之间的 import 语句。

例如:

import { a } from "./vendor-x1y2z3.js"

a()

如果使用普通脚本:

<script src="/dist/static/app-a1b2c3.js"></script>

浏览器可能出现:

Uncaught SyntaxError:
Cannot use import statement outside a module

所以需要:

<script type="module" src="/dist/static/app-a1b2c3.js"></script>

这告诉浏览器:这个文件是 ES Module,请按照模块机制加载和执行。

四、type="module" 和 defer、async 有什么区别?

特性 普通 script defer async type="module"
支持静态 import/export 否 否 否 是
下载时继续解析 HTML 否 是 是 是
默认等 HTML 解析完成再执行 否 是 否 是
多个脚本按标签顺序执行 是 是 不保证 不应依赖标签顺序
独立模块作用域 否 否 否 是

例如:

<script defer src="/js/app.js"></script>

与:

<script type="module" src="/js/app.js"></script>

都有延迟执行的效果。

但是 defer 并不能让普通脚本支持 ES Module。

另外,type="module" 一般不需要再写 defer,因为它默认就具备延迟执行行为。

五、在 GoFrame 项目中怎么使用?

建议采用两种入口:

公共入口:

<script type="module" src="/dist/static/app-a1b2c3.js"></script>

业务入口:

<script type="module" src="/dist/static/customer-e4f5g6.js"></script>

但要注意一点:不要依赖两个独立模块标签的执行先后顺序来保证 jQuery 初始化。

例如,你在 app.js 中设置:

window.$ = $

不代表另一个业务入口一定可以安全地在初始化时直接读取全局 $。

正确做法是在业务模块中显式导入:

import $ from "jquery"
import { TabulatorFull as Tabulator } from "tabulator-tables"

$(function () {
  new Tabulator("#customer-table", {
    layout: "fitColumns",
    columns: [
      { title: "客户名称", field: "name" },
      { title: "联系人", field: "contact" }
    ]
  })
})

Vite 可以根据两个入口的依赖关系提取共享代码,不需要在业务文件里手动引用 jQuery 编译后的 Hash 文件。

六、type="module" 还有两个容易忽略的特点

1. JS 文件中的变量不会自动成为全局变量。

// app.js
const name = "CRM"

以下代码不能直接访问该变量:

<script>
  console.log(name)
</script>

如果确实要跨传统脚本共享,需要显式暴露:

window.appName = "CRM"

2. 模块通过 HTTP 加载,并受到 CORS 规则约束。

开发时:

<script type="module"
        src="http://localhost:5173/src/entries/app.js"></script>

这里 Vite 和 GoFrame 使用不同端口,因此属于不同源。需要正确配置 Vite 开发服务器的 CORS。

生产环境:

<script type="module"
        src="/dist/static/app-a1b2c3.js"></script>

通常由 GoFrame 在同一个域名下提供静态资源,不需要跨域配置。

七、最终建议

对于你的技术栈:

项目 推荐方式
AdminLTE 4 通过 Vite import
jQuery 通过 Vite import
Bootstrap JS 通过 Vite import
Tabulator 通过 Vite import
ECharts 通过 Vite import
GoFrame HTML 服务端模板引擎渲染
最终 JS 引入 <script type="module">

一句话总结:

普通 <script> 是告诉浏览器“执行一个 JavaScript 文件”;而 <script type="module"> 是告诉浏览器“按照 ES Module 标准加载这个 JavaScript 模块及其依赖”。

对于 Vite 打包的现代 JavaScript 项目,使用 type="module" 是标准做法。

 


 

http://localhost:5173/assets/src/entries/app.js   为什么这个路径可以访问? http://localhost:5173/assets/@vite/client 这个的作用是啥? 前端页面不使用它行吗 ?

好问题,一次说清这三点。先做个小实验拿到直观证据:

1. 为什么 /assets/src/entries/app.js 能访问?

因为 vite dev server 本身就是一个「按需编译的静态文件服务器」。访问规则:

http://localhost:5173  +  /assets(vite.config.js 里的 base)
                       +  /src/entries/app.js(项目根 frontend/ 下的相对路径)

对比实验能直接看出它不是「原样返回文件」,而是现场转换后返回。磁盘上的源码:

import $ from "jquery"        // 裸模块名,浏览器根本不认识

vite 返回的:

import $ from "/assets/node_modules/.vite/deps/jquery.js?v=e6c08bb6"
//                  ↑ 预构建产物(esbuild 提前把依赖打包成单文件并缓存)

浏览器原生支持 ESM,vite 就把整个 node_modules 依赖解析、路径改写做好,让浏览器能逐个模块加载 —— 这就是开发模式免打包、秒级启动的原因。

2. /assets/@vite/client 是干什么的?

它是 vite 的 HMR(热更新)客户端运行时,从上面 grep 的统计也能看出来:9 处 WebSocket、42 处 hmr、10 处 overlay。作用:

功能 体验差异
与 dev server 建立 WebSocket 长连接 文件一保存,vite 推送更新事件到浏览器
CSS 热替换 改样式不刷新页面,样式立刻变(模块图未变的部分状态全保留)
JS 模块热更新 改 JS 后精准替换变更的模块;无法热替换时自动整页刷新
错误遮罩层 编译/运行报错时浏览器弹红色错误面板,修复后自动消失

ui.Tags() 在 dev 模式下把它注入为第一个 script,就是为了让后面的 app.js 等模块都在它的 HMR 管控之下。

3. 不用它行吗?

行,页面照样正常渲染和运行,它不承载任何业务逻辑。代价只有开发体验:

  • 改代码后浏览器不会自动更新,每次都要手动 Cmd + R
  • 编译错误只在终端里看,浏览器里没有任何提示

注意两点:

  1. 生产构建根本不包含它 —— APP_ENV=prod 时走 manifest 路径,产物里只有 CSS link 和业务 JS,没有 @vite/client。它是纯开发基础设施。
  2. 想去掉的话改 internal/ui/vite.go 的 dev 分支删掉那一行即可,但强烈建议保留 —— 你这个架构(Go 出页面 + vite 出资源)里,HMR 是引入 vite 的最大收益,去掉后前端开发就退化成「改一次刷一次」的原始模式了。