目录
- 一、先明确 AdminLTE 4 在整个项目中的定位
- 二、AdminLTE 4 官方项目结构分析
- 三、AdminLTE 4 页面的核心 HTML 结构
- 四、推荐的 GoFrame 工程目录结构
- 五、实战:把 AdminLTE 4 集成到 GoFrame
- 六、GoFrame 模板引擎集成
- 七、实战:CRM 客户管理页面
- 八、GoFrame 后端如何渲染页面和返回 API
- 九、二次开发:哪些功能应该封装成自己的公共组件?
- 十、生产环境编译与部署
- 十一、二次开发时最容易踩的坑
- 十二、最终开发方案
- 上述的 .vite 目录干嘛用的,为啥要加个点. 呢?
- 上述提到的 <script type="module" 的作用是啥?
- http://localhost:5173/assets/src/entries/app.js 为什么这个路径可以访问? http://localhost:5173/assets/@vite/client 这个的作用是啥? 前端页面不使用它行吗 ?
你的目标是把 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 时:
- GoFrame 路由接收请求并检查用户权限。
- Handler 查询页面所需的基础数据。
- gview 渲染 AdminLTE 的公共布局与 CRM 客户页面。
- 浏览器加载 Vite 构建的 CSS、JavaScript。
- 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 项目是否需要 |
|---|---|---|
|
|
官方 Demo 页面、公共组件 |
参考结构,移植 HTML |
|
|
AdminLTE 样式源码 |
深度主题定制时使用 |
|
|
侧边栏、卡片等交互逻辑 |
通常不必修改 |
|
|
Logo、图片等 |
按需引入 |
|
|
AdminLTE 自身的构建配置 |
不需要复制 |
|
|
已编译 CSS |
需要,通过 npm 引入 |
|
|
已编译 JS |
需要,通过 npm 引入 |
|
|
官方文档 |
不需要 |
|
|
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 模板 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
通过 Vite 资源管理统一输出 |
|
|
|
这样就不需要使用 Astro 编译 HTML。后续所有业务页面直接使用 GoFrame 的 gview 处理。
2.4 AdminLTE JavaScript 源码分析
以 src/ts/adminlte.ts 为例,官方将多个独立的插件汇总导出,随后由 Rollup 编译为 UMD 和 ESM 两种 JavaScript 资源。
|
模块 |
负责的功能 |
二次开发用途 |
|---|---|---|
|
|
主界面布局 |
页面布局控制 |
|
|
侧边栏展开和收起 |
菜单状态 |
|
|
多级菜单展开 |
CRM/SRM 多级导航 |
|
|
卡片折叠、移除、最大化 |
统计看板 |
|
|
页面全屏 |
大屏看板 |
|
|
明暗模式切换 |
用户主题偏好 |
|
|
侧边菜单搜索 |
系统导航 |
|
|
聊天窗口交互 |
在线消息 |
|
|
无障碍辅助 |
可访问性 |
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,否则可能产生样式覆盖或体积重复问题。
二次开发可分为三个级别:
|
级别 |
修改方式 |
推荐场景 |
|---|---|---|
|
简单定制 |
新建自己的 |
字体、颜色、边距、表格样式 |
|
中度定制 |
自己的 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>
© 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
}
这是一个可用于集成的基础实现。它实现了:
- 开发模式读取 Vite Dev Server。
- 生产模式读取 Manifest。
- 多入口 JS 加载。
- 递归收集依赖 CSS。
- CSS 去重。
- 自动适配构建文件的 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 处理 |
前端处理 |
|---|---|---|
|
|
输出 HTML 模板 |
AdminLTE 绘制布局 |
|
|
输出 JSON 数据 |
Tabulator 展示数据 |
|
|
返回打包文件 |
浏览器执行 JS |
|
|
返回打包文件 |
浏览器应用样式 |
这样的模式与前后端分离不同: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 结构错误 |
检查 |
|
多级菜单不展开 |
缺少 Treeview 结构或状态类 |
检查 |
|
Bootstrap 弹窗无效 |
未加载 Bootstrap JS |
检查 JS 入口 |
|
jQuery 插件报错 |
jQuery 未正确加载或初始化顺序错误 |
明确导入依赖 |
|
CSS 样式冲突 |
重复引入 Bootstrap CSS |
避免重复引入 |
|
页面 CSS 不生效 |
没有包含当前入口的 Manifest CSS |
检查资源管理代码 |
|
Vite 开发正常,生产白屏 |
文件 Hash、资源路径或 Manifest 错误 |
检查 |
|
页面出现 |
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 - 编译错误只在终端里看,浏览器里没有任何提示
注意两点:
- 生产构建根本不包含它 ——
APP_ENV=prod时走 manifest 路径,产物里只有 CSS link 和业务 JS,没有@vite/client。它是纯开发基础设施。 - 想去掉的话改
internal/ui/vite.go的 dev 分支删掉那一行即可,但强烈建议保留 —— 你这个架构(Go 出页面 + vite 出资源)里,HMR 是引入 vite 的最大收益,去掉后前端开发就退化成「改一次刷一次」的原始模式了。