@htdtcha/core-web

@htdtcha/core-web

后台管理系统通用脚手架核心包（前端）——登录鉴权 / 动态菜单路由 / 布局 / 权限指令 / 通用组件 开箱即用。

这是什么

一个前后端分离后台管理系统的前端核心。你只需要写业务页面，所有通用机制由本包提供：

技术栈：Vue 3.4+ · Vue Router 4 · Pinia 2 · Element Plus 2 · axios（消费方 Vite 5 / 6 / 7 / 8 均可）

⚠️ 本包以 .vue 源码形式发布，不做编译：动态路由要用 import.meta.glob 在构建期扫描业务页面，发布编译产物会导致业务页面无法纳入路由白名单。因此消费方必须按下文配置 optimizeDeps；包内所有自引用均为相对路径，不需要配置任何别名。

快速开始

1. 用官方命令创建 Vue 3 项目

npm create vue@latest my-admin-web     # 官方脚手架 create-vue
cd my-admin-web

交互提示按下表回答，TypeScript / Vue Router / Pinia 三项必须选 No：

生成出来是一个标准 Vue 3 + Vite 项目，自带 vite.config.js、index.html、public/favicon.ico、src/App.vue 等示例文件——下面几步都在它基础上改，不用从零手写。

💡 官方脚手架不支持「非交互 + 纯 JS」组合：npm create vue@latest x -- --default 会带上 TypeScript，而 --no-typescript 这类取反参数会被直接拒绝（ERR_PARSE_ARGS_UNKNOWN_OPTION）。想跳过交互就只能接受默认的 TS 项目，再自己补一句模块声明（见「常见问题排查」）。

2. 安装依赖

npm install        # 模板自带的 vue / vite / @vitejs/plugin-vue
npm install @htdtcha/core-web vue-router pinia element-plus @element-plus/icons-vue axios dayjs

第二行是本包 + 它的 peer 依赖。vue / vue-router / pinia / element-plus 必须只有一份（由你的项目提供），装双份会出现组件实例不一致、样式重复、getActivePinia() 报错等问题。

3. 改 vite.config.js（3 处必配 + 1 段代理）

import { fileURLToPath, URL } from 'node:url'

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import vueDevTools from 'vite-plugin-vue-devtools' // 模板自带，保留即可

export default defineConfig({
  plugins: [vue(), vueDevTools()],
  resolve: {
    alias: {
      // 模板自带：项目内别名（业务模块用）
      '@': fileURLToPath(new URL('./src', import.meta.url))
    }
  },
  // ★ 必配 1：optimizeDeps 的两个键缺一不可
  optimizeDeps: {
    // (a) 禁止 Vite 预打包 .vue 源码包。不配会报「.vue 被当二进制 / Invalid tag」，
    //     或让包被复制成多份实例
    exclude: ['@htdtcha/core-web'],

    // (b) 把本包的依赖显式拉进预打包。原因：Vite 的依赖扫描器不会爬进被
    //     exclude 的包，只能靠你项目自身的源码发现依赖——业务模块还没写的
    //     时候什么也发现不了，所有依赖都会以 node_modules 裸源码直出，
    //     其中 dayjs 是 UMD，浏览器裸加载会报
    //     "does not provide an export named 'default'"（详见「常见问题排查」第 1 条）。
    //     下面 7 个就是本包源码里直接 import 的全部三方依赖。
    include: [
      'vue',
      'vue-router',
      'pinia',
      'element-plus',
      '@element-plus/icons-vue',
      'axios',
      'dayjs'
    ]
  },
  // ★ 必配 2：把 /api 代理到后端（core-server 默认 3000）
  server: {
    proxy: {
      '/api': { target: 'http://localhost:3000', changeOrigin: true },
      '/uploads': { target: 'http://localhost:3000', changeOrigin: true }
    }
  }
})

就这样，不需要给本包配任何别名。

为什么 include 必须配？ exclude 只是「不要预打包这个包」，它不会让 Vite 继续去预打包这个包的依赖——Vite 改为完全依赖你项目自身源码去「发现」依赖。一旦项目里没有任何文件直接 import vue / element-plus / dayjs（典型场景：刚建好项目、业务模块还没写），Vite 就一个依赖都不预打包，全部裸源码直出。纯 ESM 的包裸跑没问题，但 dayjs 是 UMD，于是首屏直接报错。

生产分包提示：

• Vite 8（Rolldown 内核）：默认分包已经够用，构建不会出现跨 chunk 循环；要精细控制用 build.rolldownOptions.output.codeSplitting。
• Vite ≤7（Rollup 内核）：若手动写 manualChunks，请用 function-form + 反向 catch-all（小名单 vue|vue-router|pinia|axios → vendor，其余第三方全部 → element-plus chunk）。枚举 element-plus 生态的写法会漏包，触发 Circular chunk: element-plus -> vendor -> element-plus，运行时表现为 Cannot access 'X' before initialization（TDZ）。

4. 改 index.html（模板已生成，改 3 处）

模板生成的是 <html lang=""> + <title>Vite App</title>，改成：

<!DOCTYPE html>
<html lang="zh-CN" class="dark">
  <head>
    <meta charset="UTF-8">
    <link rel="icon" href="/favicon.ico">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>后台管理系统</title>
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/src/main.js"></script>
  </body>
</html>

5. 清理模板示例文件 + 替换 src/main.js

# 模板的示例页面与样式不再需要（App.vue 由本包提供）
rm -rf src/components src/assets src/App.vue

Windows PowerShell：Remove-Item -Recurse -Force src/components, src/assets, src/App.vue

src/main.js 全部内容（3 行）：

import { createAdmin } from '@htdtcha/core-web'
import { businessViews } from './views'

createAdmin({ businessViews }).mount('#app')

6. src/views.js（业务视图白名单，必须由项目侧提供）

/**
 * import.meta.glob 的路径解析发生在「定义它的文件」所在位置，
 * 所以业务页面的 glob 必须写在业务项目代码里，再传给 createAdmin。
 */
export const businessViews = import.meta.glob('./*/views/**/*.vue')

7. 写你的第一个业务模块

见下文「业务模块（module-first）」。

8. 装后端 + 建菜单

本包需配合 @htdtcha/core-server 使用（后端初始化见该包 README）。后端起好后，菜单有两条路：

A. 手动建：在菜单管理里新增一条——类型 C（菜单）、路径 /biz/customer（父目录 /biz「业务示例」）、组件填 customer/index，再在角色管理里勾上 biz:customer:* 权限点。

B. 用业务种子自动建（推荐）：在业务项目里放 src/customer/seeders/001_customer_demo.js（文件里幂等插入菜单与权限点），然后

npx admin-seed --scope business    # 只跑业务种子；不加参数则系统+业务全跑

种子按「先查存在性再插入」幂等创建菜单与权限点，重跑无副作用。

业务模块（module-first）

业务模块自包含，直接放在项目 src/ 下，不要 src/business/ 之类的中间层：

src/
├── views.js                    # 视图白名单 glob（必须）
├── main.js
└── customer/                   # 业务模块（与后端 src/customer/ 对称）
    ├── api.js                  # 接口封装（用包导出的 request）
    └── views/
        └── index.vue           # 页面（菜单 component 填 customer/index）

src/customer/api.js 示例：

import { request } from '@htdtcha/core-web'

/** 客户列表（分页） */
export function listCustomer(params) {
  return request.get('/customer', { params })
}

/** 新增客户 */
export function createCustomer(data) {
  return request.post('/customer', data)
}

src/customer/views/index.vue 示例（用包导出的通用组件与权限组件）：

<script setup>
import { PageContainer, AuthButton, request } from '@htdtcha/core-web'
import { listCustomer } from '../api'
</script>

<template>
  <PageContainer title="客户管理">
    <AuthButton auth="biz:customer:add" type="primary" @click="openCreate">新增客户</AuthButton>
    <!-- ... -->
  </PageContainer>
</template>

菜单 component 字段 → 视图文件的映射规则（双源解析）

路由注册时按下面的顺序查表，两个源都没命中就 console.warn 并跳过（防注入：非法路径无法注册成路由）：

业务页的 glob key 形如 ./customer/views/index.vue，由包内 resolveView() 按 ./{第一段}/views/{其余段}.vue 规则拼出。所以业务模块必须是 views/ 子目录这一层结构。

包导出 API

createAdmin(options)

创建并配置好 Vue 应用实例（已挂 pinia / router / ElementPlus / 图标 / v-permission 指令，并启动公开配置拉取与响应式监听）。返回 app，直接 .mount('#app')。

其它导出

import {
  // HTTP 基座（业务 api.js 用）
  request,
  // token 管理
  getToken, setToken, removeToken,
  // 权限判断（有权限点返回 true）
  hasPerm,
  // store
  useAppStore, useUserStore, usePermissionStore,
  // 路由
  createAdminRouter, getRouter, buildRoutesFromMenus, resolveView,
  // 通用组件
  PageContainer, AuthButton, AuthWrapper,
  // 认证 API
  login, sendCode, logout, refresh, getProfile, updateProfile, changePassword, getMyMenus
} from '@htdtcha/core-web'

权限指令 / 组件

<!-- 指令：无权限时元素从 DOM 移除 -->
<el-button v-permission="'biz:customer:add'">新增</el-button>

<!-- 组件：无权限时不渲染（更省心，无需自己包 template） -->
<AuthButton auth="biz:customer:add" type="primary" @click="openCreate">新增客户</AuthButton>

与后端对接约定

常见问题排查

配套包

License

MIT