应直接修改 src/scss/ 和 src/ts/ 中的源文件，避免改动 dist/ 下编译结果；样式定制通过 _variables.scss 和 adminlte.scss 中的 $ 变量统一控制；功能扩展需封装为独立 TS 模块并挂载到 app.ts；布局调整优先复用 src/html/pages/layout/ 中的完整 HTML 骨架。
直接改 src/scss/ 和 src/ts/，别碰 dist/ 里的文件——那是编译结果，改了下次 npm run production 就被覆盖。
改样式：从 adminlte.scss 入口开始调变量
AdminLTE 的 SCSS 结构不是一锅炖，所有主题色、间距、断点都集中在 src/scss/_variables.scss 和 src/scss/adminlte.scss 开头的 $ 变量里。比如想换主色调，只用改这一行：
$primary: #1e40af; // 原来是 #007bff
改完保存，npm run dev 会自动重编译，浏览器立刻生效。别去搜 .card-header 在哪定义的——它由 _cards.scss 控制，而这个文件在 adminlte.scss 里被 import，变量统一走上面那套。
容易踩的坑：
- 直接在
dist/css/adminlte.css里手写 CSS 覆盖，上线后发现没生效——因为生产环境用的是压缩版，且不走你手动加的规则 - 在
index.html里用<style></style>标签写覆盖样式，结果移动端侧边栏收起逻辑错乱——部分 JS 插件（如push-menu.ts）依赖 class 名匹配，硬加样式可能破坏 DOM 判断 - 改了
$sidebar-width但菜单没变宽——得同步检查_app-sidebar.scss里是否用了固定像素值（比如width: 250px），变量没透传到那里
加功能：优先封装成独立 TS 模块，再挂到 src/ts/
AdminLTE 的交互逻辑全在 src/ts/ 下，每个文件对应一个可插拔行为：treeview.ts 管树形菜单，card-widget.ts 管卡片折叠。你要加个「导出 Excel」按钮，别把逻辑塞进 index.html 的 <script></script> 里，而是新建 src/ts/export-excel.ts：
export function initExportButton() {
document.querySelectorAll('[data-export]').forEach(btn => {
btn.addEventListener('click', () => {
// 这里调用 SheetJS 或其他库
})
})
}
然后在 src/ts/app.ts 的末尾加一行 initExportButton()。这样后续升级 AdminLTE 主版本时，你的代码只在自己文件里，不会和官方 app.ts 冲突。
注意兼容性：
- 不要在新模块里直接操作
document.body.classList.add('sidebar-collapse')——这是 AdminLTE 内部状态，应该用它暴露的SideBar类或事件（如sidebar:collapsed） - 如果要用第三方库（如 Chart.js），别用 CDN 引入；
npm install chart.js后，在 TS 文件里import { Chart } from 'chart.js'，否则构建时可能找不到类型定义 - Vue/React 项目里嵌 AdminLTE 页面？别让
push-menu.ts直接操作 DOM——用框架的 ref 或事件总线接管 sidebar 显示逻辑，否则两边状态不同步
换布局：复用 src/html/pages/layout/ 里的 HTML 结构
AdminLTE 提供的布局不是靠 JS 切换 class 实现的，而是真·不同 HTML 文件：fixed-sidebar.html、collapsed-sidebar.html 都是完整骨架。你要用「固定侧边栏 + 折叠菜单」组合，别自己拼 class，直接复制 src/html/pages/layout/fixed-sidebar.html 到项目页面目录，再删掉不需要的区块（比如顶部通知栏）。
关键细节：
- 所有布局页都依赖同一套 JS 初始化逻辑（
src/ts/app.ts），所以只要结构 class 名不变（如main-sidebar、content-wrapper），你的自定义布局就能自动获得折叠/展开行为 - 如果删了
<div class="main-header">，记得同步删掉 <code>src/ts/app.ts里对它的初始化调用，否则控制台会报Cannot read property 'addEventListener' of null - RTL（从右向左）布局要启用，不只是改
dir="rtl"，还得在adminlte.scss里取消注释@import "rtl";并确保字体支持阿拉伯语字符
最常被忽略的一点：AdminLTE 的「深色主题」不是开关式切换，而是通过 dark-mode class + 一套独立的 SCSS 变量控制。如果你只在 HTML 上加 class 却没启用 _dark-mode.scss 的 import，夜间模式只会变黑背景，文字和组件颜色依然按白天逻辑渲染——看起来像 bug，其实是漏了一行 import。
