laybot-vite-dev 0.1.0 → 1.0.0

package/README.md

@@ -1,55 +1,79 @@
 # laybot-vite-dev
 
-Vite 开发服务器适配插件，用于 **LarryMS MPA（多页）+ runtime loader（`larryms.use`）** 的开发模式。
+`laybot-vite-dev` 是 Laybot/LarryMS MPA 项目在 **Vite 开发模式**下的 URL 重写适配插件。
 
-它解决的核心问题是：LarryMS 在浏览器里按 **固定 URL 前缀**请求资源（如 `/assets/**`、`/laybot/**`、`/static/**`），但在 Vite dev 下源码实际位于 `src/**`。本插件会在 dev server 中间件层做 URL 重写，使 **开发环境访问路径与生产环境一致**，且不会破坏 Vite HMR WebSocket。
+它的目标是：让浏览器在 dev 环境仍然可以按“生产环境路径”访问资源与模块，例如：
+
+- `/laybot/larryms.js`
+- `/static/css/admin.dark.css`
+- `/api/common.js`
+- `/assets/app/main.js`
+
+同时 **不破坏 Vite HMR 的 WebSocket 连接**。
 
 ---
 
-## 特性
+## 为什么需要它？
 
-- **MPA HTML 路由映射**
-    - `/`、`/index.html` → `src/views/index.html`
-    - `/xxx.html` → `src/views/xxx.html`
-- **统一业务根目录 `/assets/`**
-    - `/assets/**` → `/src/**`（去掉 `assets` 前缀）
-    - 推荐 LarryMS MPA 项目统一把业务模块/资源发布在生产环境的 `dist/assets/**`
-- **框架运行时 `/laybot/` 映射**
-    - `/laybot/**` → `/src/laybot/**`
-- **静态资源 `/static/` 映射**
-    - `/static/**` → `/src/static/**`
-- **兼容旧写法 `/app/`**
-    - `/app/**` → `/src/app/**`（可用于过渡期或老项目）
-- **不会破坏 Vite HMR**
-    - 自动放行 WebSocket upgrade 与 Vite 内部路径（`/@vite`、`/@id`、`/@fs`、`/__vite`…）
+LarryMS/Laybot 的 runtime loader（`larryms.use`）会在浏览器端动态插入 `<script src="...">` 加载模块。  
+在生产环境这些模块位于 `dist/` 目录结构下，而在 Vite dev 环境源码通常位于 `src/`。
 
----
+如果不做 URL 映射，开发环境会出现大量 404（例如请求 `/api/common.js`，但文件真实在 `src/api/common.js`）。
 
-## 适用场景
+本插件通过 Vite middleware 把这些 URL 改写到源码目录，从而实现：
 
-- 你使用 LarryMS（`larryms.define/larryms.use`）做模块加载
-- 项目是 MPA：每个页面一个 `.html`，不走 Vue/React SPA 路由
-- 构建产物约定：
-    - `dist/index.html`、`dist/login.html`（或更多页面）
-    - `dist/assets/**`（业务模块与资源）
-    - `dist/laybot/**`（框架运行时）
-    - `dist/static/**`（静态资源）
+- **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`
+
+
 ## 安装
 
 ```bash
 npm i -D laybot-vite-dev
 ```
 
-> 如果你使用 pnpm/yarn 也可对应安装。
-
----
-
 ## 使用
 
-在项目的 `vite.config.js` 中引入并加入 plugins：
+在 `vite.config.js` 中使用：
 
 ```js
 import { defineConfig } from 'vite'
@@ -58,43 +82,31 @@ import laybotViteDev from 'laybot-vite-dev'
 export default defineConfig({
   server: { port: 5173 },
   plugins: [
-    laybotViteDev({
-      debug: false
-    })
+    laybotViteDev()
   ]
 })
 ```
 
-然后访问：
 
-- http://localhost:5173/        → `src/views/index.html`
-- http://localhost:5173/login.html → `src/views/login.html`
+## 自定义：增加更多业务目录（例如 /service/）
 
-页面里引用的生产路径在 dev 下仍然可用，例如：
+如果你新增了源码目录：
 
-```html
-<link rel="stylesheet" href="/laybot/css/larryms.css" />
-<link rel="stylesheet" href="/static/css/admin.dark.css" />
-<script src="/laybot/larryms.js"></script>
-<script src="/assets/app/laybot.js"></script>
-```
+- `src/service/**`
 
----
+并希望 dev 下可以请求：
 
-## 约定与规范（重要）
+- `/service/xxx.js` → `/src/service/xxx.js`
 
-### 1）业务模块统一发布到 `/assets/`
-LarryMS MPA 建议约定：生产环境业务模块都在 `/assets/` 下。
+只需：
 
-- 好处：URL 语义统一、构建结构稳定、文档清晰、CDN 缓存策略统一
-- 你的源码可以自由组织（`src/app`、`src/biz`、`src/features`…），最终只要构建输出到 `dist/assets/**` 即可
-
-### 2）框架运行时固定 `/laybot/`
-- `larryms.js` 与框架 css/font/images 固定在 `dist/laybot/**`
-- 业务项目无需理解其内部结构，只要按固定 URL 引用即可
+```js
+laybotViteDev({
+  toSrcPrefixes: ['/service/']
+})
+```
 
-### 3）静态资源固定 `/static/`
-- 例如主题 css、svg、音频等放在 `dist/static/**`
+> 注意：**不需要手动拼接默认前缀列表**。插件会自动把你的 `toSrcPrefixes` 与默认列表合并（去重）。
 
 ---
 
@@ -102,58 +114,55 @@ LarryMS MPA 建议约定：生产环境业务模块都在 `/assets/` 下。
 
 ```js
 laybotViteDev({
-  viewsDir: '/src/views',     // 默认：/src/views
-  assetsPrefix: '/assets/',   // 默认：/assets/
-  laybotPrefix: '/laybot/',   // 默认：/laybot/
-  staticPrefix: '/static/',   // 默认：/static/
-  appPrefix: '/app/',         // 默认：/app/（兼容用）
-  debug: false                // 默认 false；true 时打印 rewrite 前后关系
-})
-```
-
-### debug
-开启后会输出每次重写的映射结果，便于定位 404：
-
-```bash
-[laybot-vite-dev] /static/css/admin.dark.css => /src/static/css/admin.dark.css
-```
+  // MPA views 源目录
+  viewsDir: '/src/views',
 
----
+  // / 映射用的首页文件名
+  htmlFallback: 'index.html',
 
-## 常见问题
+  // 源码根目录（一般固定 /src）
+  srcRoot: '/src',
 
-### 1）`[vite] failed to connect to websocket`
-原因：你在 Vite dev 中间件里重写了 WebSocket upgrade 请求（HMR 握手），导致连接失败。
+  // 需要直接映射到 /src 的前缀（可追加）
+  toSrcPrefixes: ['/service/'],
 
-本插件已内置放行：
-- `upgrade: websocket`
-- `/@vite`、`/@id`、`/@fs`、`/__vite` 等 Vite 内部路径
+  // 需要去掉前缀再映射到 /src 的前缀
+  stripPrefixes: ['/assets/'],
 
-若你自行添加了其它中间件，请确保它们不会重写 WebSocket 请求。
+  // 输出映射日志
+  debug: false
+})
+```
 
 ---
 
-### 2）`/laybot/larryms.js 404` 或 `/static/... 404`
-请确认文件存在于源码目录：
+## 常见问题
 
-- `src/laybot/larryms.js`
-- `src/laybot/css/larryms.css`
-- `src/static/css/...`
-- `src/app/laybot.js`
+### 1) dev 下出现大量 404
+请检查：
+- 插件是否已加入 Vite plugins
+- 相关文件是否存在于 `src` 对应目录
+- 是否请求了未在前缀列表中的路径（可通过 `toSrcPrefixes` 追加）
 
-并确认插件已加入 Vite plugins 列表且 dev server 已重启。
+### 2) `[vite] failed to connect to websocket`
+一般是你项目里其它中间件/代理重写了 WebSocket upgrade 请求。  
+本插件已做放行，但如果你自己还写了 `middlewares.use`，请确保对 `upgrade: websocket` 的请求不要重写 `req.url`。
 
 ---
 
-### 3）为什么插件要强制统一 `/assets/`？
-因为 LarryMS 的 runtime loader 会动态加载业务模块。如果允许业务模块在 dev/prod 中出现多套 URL 体系（例如 dev 用 `/api/*.js`，prod 用 `/assets/*.js`），很容易出现：
-- 某个页面忘了更新路径导致 404
-- devRewrite 规则越来越多、越来越难维护
-- MPA 页面之间初始化逻辑分裂
+## 推荐约定（稳定的大项目规范）
 
-统一 `/assets/` 可以让开发环境与生产环境保持一致，减少路径问题。
+- 生产结构建议固定为：
+  - `dist/laybot/**` 框架
+  - `dist/static/**` 静态资源
+  - `dist/assets/**` 业务产物（推荐统一业务模块 root）
+
+- 开发环境路径建议与生产一致：
+  - 页面里引用 `/laybot/**`、`/static/**`
+  - 模块可使用 `/assets/**` 或框架内置的 `/api/ /route/ ...` 等目录
 
 ---
 
 ## License
-MIT (建议你根据实际发布策略修改许可证说明)
+
+LayBot Grant PPL

package/dist/index.js

@@ -1 +1 @@
-function c(u={}){let i={viewsDir:u.viewsDir||"/src/views",debug:u.debug===!0,assetsPrefix:u.assetsPrefix||"/assets/",laybotPrefix:u.laybotPrefix||"/laybot/",staticPrefix:u.staticPrefix||"/static/",appPrefix:u.appPrefix||"/app/"},l=(...f)=>i.debug&&console.log("[laybot-vite-dev]",...f);return{name:"laybot-vite-dev",enforce:"pre",configureServer(f){f.middlewares.use((r,o,e)=>{let a=r.url||"/",[t,s=""]=a.split("?");if((r.headers.upgrade||"").toLowerCase()==="websocket"||t.startsWith("/@vite")||t.startsWith("/@id")||t.startsWith("/@fs")||t.startsWith("/__vite")||t==="/favicon.ico")return e();if(t==="/"||t==="/index.html")return r.url=`${i.viewsDir}/index.html`+(s?`?${s}`:""),l(a,"=>",r.url),e();if(/\.html$/i.test(t)&&!t.startsWith(i.viewsDir+"/"))return r.url=`${i.viewsDir}${t}`+(s?`?${s}`:""),l(a,"=>",r.url),e();if(t.startsWith(i.assetsPrefix))return r.url="/src"+t.slice(i.assetsPrefix.length-1)+(s?`?${s}`:""),l(a,"=>",r.url),e();if(t.startsWith(i.laybotPrefix))return r.url="/src"+t+(s?`?${s}`:""),l(a,"=>",r.url),e();if(t.startsWith(i.staticPrefix))return r.url="/src"+t+(s?`?${s}`:""),l(a,"=>",r.url),e();if(t.startsWith(i.appPrefix))return r.url="/src"+t+(s?`?${s}`:""),l(a,"=>",r.url),e();e()})}}}export{c as default};
+var d=Object.freeze({srcRoot:"/src",viewsDir:"/src/views",htmlFallback:"index.html",debug:!1,toSrcPrefixes:["/api/","/route/","/mock/","/store/","/utils/","/plugin/","/components/","/laybot/","/static/","/app/"],stripPrefixes:["/assets/"]});function v(i){let c=[],f=new Set;for(let r of i||[]){let o=String(r||"").trim();o&&(f.has(o)||(f.add(o),c.push(o)))}return c}function l(i,c){return i+(c?`?${c}`:"")}function b(i={}){let c=i.prefixes||i.toSrcPrefixes||[],f=i.strip||i.stripPrefixes||[],r={...d,...i,toSrcPrefixes:v([...d.toSrcPrefixes,...c]),stripPrefixes:v([...d.stripPrefixes,...f])},o=(...h)=>{r.debug&&console.log("[laybot-vite-dev]",...h)};return{name:"laybot-vite-dev",enforce:"pre",configureServer(h){h.middlewares.use((e,m,n)=>{let u=e.url||"/",[t,a=""]=u.split("?");if((e.headers.upgrade||"").toLowerCase()==="websocket"||t.startsWith("/@vite")||t.startsWith("/@id")||t.startsWith("/@fs")||t.startsWith("/__vite")||t==="/favicon.ico")return n();if(t==="/"||t==="/index.html"){let s=`${r.viewsDir}/${r.htmlFallback}`;return e.url=l(s,a),o(u,"=>",e.url),n()}if(/\.html$/i.test(t)&&!t.startsWith(r.viewsDir+"/")){let s=`${r.viewsDir}${t}`;return e.url=l(s,a),o(u,"=>",e.url),n()}for(let s of r.stripPrefixes)if(s&&t.startsWith(s)){let p=t.slice(s.length-1),S=`${r.srcRoot}${p}`;return e.url=l(S,a),o(u,"=>",e.url),n()}for(let s of r.toSrcPrefixes)if(s&&t.startsWith(s)){let p=`${r.srcRoot}${t}`;return e.url=l(p,a),o(u,"=>",e.url),n()}return n()})}}}export{b as default};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "laybot-vite-dev",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "Vite dev rewrite plugin for LayBot/LarryMS MPA runtime loader",
   "type": "module",
   "main": "dist/index.js",