befly-vite

Befly 项目（Vue 3 + Vite 8）的构建配置预设与文件路由体系。

• 配置预设：一行生成 Vite 配置（自动路由、组件注册、CSS 优化、依赖预构建）
• 文件路由：目录即路由，$布局名 后缀指定布局，构建期一次成型，浏览器端零规则
• CLI：Bun 环境下的 Vite 启动包装器

安装

bun add -d befly-vite

快速开始

vite.config.js

import { fileURLToPath } from "node:url";
import { createBeflyViteConfig } from "befly-vite";

export default createBeflyViteConfig({
    root: fileURLToPath(new URL(".", import.meta.url))
});

src/plugins/router.js

import { createRouter, createWebHashHistory } from "vue-router";
import { routes } from "vue-router/auto-routes";

import { $Config } from "@/configs/config.js";

// 根路径重定向（homePath 为空或 "/" 时不注入；路由与布局已在构建期生成）
const finalRoutes = $Config.homePath && $Config.homePath !== "/" ? [{ path: "/", redirect: $Config.homePath }].concat(routes) : routes;

export const $Router = createRouter({
    history: createWebHashHistory(import.meta.env.BASE_URL),
    routes: finalRoutes
});

文件路由与布局

目录即路由

src/views 下的目录与文件自动生成路由：

| 文件 | 路由 | | ---------------------------------- | ------------------------------------------- | | src/views/index/index.vue | /（index 段折叠为空） | | src/views/core/index/index.vue | /core（框架视图，见下） | | src/views/userCenter/account.vue | /user-center/account（段自动 kebab 转换） | | src/views/user/[userId].vue | /user/:userId（动态段保留） |

框架视图（befly-admin-ui）

后台管理项目安装 befly-admin-ui 后，其 views 目录自动以 core/ 前缀并入路由。普通网站没有该包时自动跳过。

布局：$布局名 后缀

布局名写在目录或文件名里，不需要任何配置文件：

| 写法 | 含义 | | ------------------------------------- | --------------------------------------------------- | | views/guide$admin/index.vue | guide 目录及其子孙使用 admin 布局（→ /guide） | | views/account$none.vue | 该页面使用 none 布局 | | views/guide$admin/detail$simple.vue | 文件级 $simple 覆盖目录级 admin |

规则：

1. 段名中最后一个 $ 之后为布局名，$ 之前为主体（路径不含 $）
2. 无 $ 的子孙目录沿用最近父级的布局（继承）
3. 文件级 $布局 覆盖目录级继承
4. 全程无 $ 时使用 default 布局
5. 布局名对应布局文件：befly-admin-ui/layouts/{name}.vue 优先，其次 src/layouts/{name}.vue；找不到时构建期报错
6. 页面组件被包装为：布局组件（父路由，自带 <RouterView/>）+ 空 path 子路由（页面组件），懒加载保留

构建期转换

所有转换（$ 剥离、kebab、index 折叠、布局包装）在 vue-router/vite 的 beforeWriteFiles 钩子内构建期一次完成，生成的 vue-router/auto-routes 即最终路由。浏览器端 createRouter(routes) 直接使用，无任何运行时规则。

createBeflyViteConfig

createBeflyViteConfig({
    root, // 项目根目录（默认 process.cwd()）
    analyzer, // 是否启用 bundle 分析（默认 false）
    resolvers, // 自定义组件 resolvers（对象或数组）
    manualChunks, // 便捷分包，写入 build.rolldownOptions.output.manualChunks
    viteConfig, // 用户配置，与预设深度合并（数组合并、对象深合并）
    resolveLayout // 布局名 → 布局文件路径（默认 adminUI 优先 + src/layouts 兜底）
});

内置默认

• 插件：vue-router/vite 自动路由（beforeWriteFiles 构建期布局转换）、@vitejs/plugin-vue、组件自动注册
• 别名：@ → src
• CSS：Lightning CSS 转换与压缩（build.cssTarget 与 css.lightningcss.targets 默认目标见源码）
• 预构建：vue、vue-router、pinia + tdesign-vue-next/tdesign-icons-vue-next（仅项目安装了 TDesign 时加入，与用户 optimizeDeps.include 数组合并）
• 构建：base: "./"、outDir: "dist"、assetsDir: "assets"

覆盖行为

viteConfig 通过 Vite mergeConfig 合并。注意：

• optimizeDeps.include 为数组合并（默认项与用户项共存）
• build.cssTarget 为数组，合并后强制取用户值（如需覆盖，直接在 viteConfig.build.cssTarget 传入）

scanViews

扫描路由视图目录，返回 [{ src, path, exclude }]：

import { scanViews } from "befly-vite";

scanViews(appRoot);
// [
//   { src: ".../src/views", path: "", exclude: ["**/components/**"] },
//   { src: ".../node_modules/befly-admin-ui/views", path: "core/", exclude: ["**/components/**"] }
// ]

项目无 src/views 或无 befly-admin-ui 时对应来源自动跳过。befly-admin-ui 从项目目录逐级向上查找（兼容 bun workspace 依赖提升到根 node_modules）。

组件自动注册

• 扫描目录：src/components（deep）
• 默认 resolver：TDesign Vue Next、tdesign-icons-vue-next 图标、自定义 resolvers
• node_modules 默认排除，befly-admin-ui 内置视图放行

CLI

bunx befly-vite dev       # 启动开发（需要清依赖缓存时手动加 --force）
bunx befly-vite build
bunx befly-vite preview

本质是 Bun 环境下的 Vite 启动包装器：定位 vite/bin/vite.js 并原样转发参数。

布局约定速查

| 场景 | 写法 | 结果 | | -------- | ------------------------------- | ------------------------------ | | 默认布局 | views/home.vue | default 布局 | | 单页指定 | views/account$none.vue | /account，none 布局 | | 目录统一 | views/guide$admin/ | 目录内页面继承 admin 布局 | | 覆盖继承 | guide$admin/detail$simple.vue | /guide/detail，simple 布局 | | 多级继承 | a$admin/b/c.vue | /a/b/c，admin 布局 |