laybot-vite-dev

laybot-vite-dev 是 Laybot/LarryMS MPA 项目在 Vite 开发模式下的 URL 重写适配插件。

它的目标是：让浏览器在 dev 环境仍然可以按“生产环境路径”访问资源与模块，例如：

• /laybot/larryms.js
• /static/css/admin.dark.css
• /api/common.js
• /assets/app/main.js

同时 不破坏 Vite HMR 的 WebSocket 连接。

为什么需要它？

LarryMS/Laybot 的 runtime loader（larryms.use）会在浏览器端动态插入 <script src="..."> 加载模块。
在生产环境这些模块位于 dist/ 目录结构下，而在 Vite dev 环境源码通常位于 src/。

如果不做 URL 映射，开发环境会出现大量 404（例如请求 /api/common.js，但文件真实在 src/api/common.js）。

本插件通过 Vite middleware 把这些 URL 改写到源码目录，从而实现：

• MPA 页面开发体验稳定
• dev/prod 路径语义一致
• 无需在每个页面写大量初始化逻辑
• HMR 不会挂

特性

1) MPA HTML 路由映射

• /、/index.html → /src/views/index.html
• /xxx.html → /src/views/xxx.html

2) 默认支持的目录前缀（开箱即用）

以下请求会自动映射到 /src：

| 请求 URL 前缀 | dev 映射目标 | |---|---| | /api/ | /src/api/ | | /route/ | /src/route/ | | /mock/ | /src/mock/ | | /store/ | /src/store/ | | /utils/ | /src/utils/ | | /plugin/ | /src/plugin/ | | /components/ | /src/components/ | | /laybot/ | /src/laybot/ | | /static/ | /src/static/ | | /app/ | /src/app/ |

此外还支持“去前缀”映射（默认启用）：

• /assets/** → /src/**（去掉 assets 前缀）

说明：这套默认值就是 LarryMS/Laybot 框架在 MPA 模式下常见的目录结构，保证你现有项目无需改动就能跑。

3) HMR WebSocket 安全放行

插件会自动放行：

• upgrade: websocket 的请求（Vite HMR）
• Vite 内部路径（/@vite、/@id、/@fs、/__vite 等）

避免出现：

• [vite] failed to connect to websocket

安装

npm i -D laybot-vite-dev

使用

在 vite.config.js 中使用：

import { defineConfig } from 'vite'
import laybotViteDev from 'laybot-vite-dev'

export default defineConfig({
  server: { port: 5173 },
  plugins: [
    laybotViteDev()
  ]
})

自定义：增加更多业务目录（例如 /service/）

如果你新增了源码目录：

• src/service/**

并希望 dev 下可以请求：

• /service/xxx.js → /src/service/xxx.js

只需：

laybotViteDev({
  toSrcPrefixes: ['/service/']
})

注意：不需要手动拼接默认前缀列表。插件会自动把你的 toSrcPrefixes 与默认列表合并（去重）。

配置项

laybotViteDev({
  // MPA views 源目录
  viewsDir: '/src/views',

  // / 映射用的首页文件名
  htmlFallback: 'index.html',

  // 源码根目录（一般固定 /src）
  srcRoot: '/src',

  // 需要直接映射到 /src 的前缀（可追加）
  toSrcPrefixes: ['/service/'],

  // 需要去掉前缀再映射到 /src 的前缀
  stripPrefixes: ['/assets/'],

  // 输出映射日志
  debug: false
})

常见问题

1) dev 下出现大量 404

请检查：

• 插件是否已加入 Vite plugins
• 相关文件是否存在于 src 对应目录
• 是否请求了未在前缀列表中的路径（可通过 toSrcPrefixes 追加）

2) [vite] failed to connect to websocket

一般是你项目里其它中间件/代理重写了 WebSocket upgrade 请求。
本插件已做放行，但如果你自己还写了 middlewares.use，请确保对 upgrade: websocket 的请求不要重写 req.url。

推荐约定（稳定的大项目规范）

• 生产结构建议固定为：

  • dist/laybot/** 框架
  • dist/static/** 静态资源
  • dist/assets/** 业务产物（推荐统一业务模块 root）

• 开发环境路径建议与生产一致：

  • 页面里引用 /laybot/**、/static/**
  • 模块可使用 /assets/** 或框架内置的 /api/ /route/ ... 等目录

License

LayBot Grant PPL