@lark-apaas/coding-html-devserver

miaoda-coding html stack 的 dev/build 工具链。vite 被封装在内部——消费方（html 模板）只依赖本包、调它的 bin,**package.json 里看不到 vite、也没有 vite.config**。

• dev:内部用 vite 起 dev server,拿 vite 原生 HMR/热更新(WS,经 MIAODA_WS_HOST 切独立域名穿沙箱网关) + /dev/health 探活 + 平台脚本注入。
• build:不走 vite build,纯拷贝 src → dist/output(文件名/路径/结构逐字保留)+ 平台脚本注入 + 可选 HTML 压缩。
• 平台脚本注入:dev / build 共用一份清单,用户不感知、源文件保持纯净。

为什么这么设计

html stack 要的是 vite 那种即时热更新体验(轮询追不上),所以 dev 直接借 vite;但 vite build 会打包/加 hash/改写路径,跟"纯 HTML 产物 = 源码"冲突,所以 build 自己做纯拷贝。vite 全程是本包的内部依赖,对用户透明。

用法

// 消费方（html 模板）package.json —— 全程不出现 vite
"devDependencies": { "@lark-apaas/coding-html-devserver": "^0.1.0" },
"scripts": {
  "dev":   "coding-html-devserver dev",
  "build": "coding-html-devserver build"
}

coding-html-devserver dev   [--root src] [--port 8001] [--host 0.0.0.0]
coding-html-devserver build [--root src] [--out dist/output] [--no-minify]

端口优先级:--port > CLIENT_DEV_PORT env > 8001。绑定 0.0.0.0、allowedHosts: true、不设 base(prefix 由沙箱网关剥)。HMR 在 MIAODA_WS_HOST 存在时切独立 WS 域名(对齐 vite-react 网关方案)。

平台注入(方案 A:烧进 SDK)

注入清单是内部常量 PLATFORM_TAGS,随版本走、用户不可配置。改注入 = 发新版 → 模板 bump → re-render。注入实现只有一份(injectTags),dev 经 vite transformIndexHtml 插件调用、build 在拷贝后调用,两条路一致。

描述符对齐 vite 的 HtmlTagDescriptor:

{ tag: 'script', attrs: { src: 'https://cdn/x.js', async: true }, injectTo: 'head' } // 外链 CDN
{ tag: 'script', children: 'window.__X__=1', injectTo: 'head-prepend' }              // 内联 JS

机制:按 injectTo 分组保序、同 src/id 去重、内联 </script> 转义、畸形 HTML 锚点兜底。

当前 PLATFORM_TAGS 为占位空清单;机制已完整实现并测试,真实平台脚本地址确定后填入即可,对 API 无影响。

公共 API

startDevServer · buildStatic · createHtmlViteConfig · injectPlatformTags · injectTags · serializeTag · healthPlugin · platformInjectPlugin · 类型 HtmlTagDescriptor 等。

工程

ESM 包(vite 8 仅 ESM)。tsc → lib/(NodeNext)。Node ≥22。

设计文档:docs/superpowers/plans/2026-06-05-html-devserver-sdk.md