@lark-apaas/coding-static-server

miaoda-coding 沙箱预览用的轻量静态文件 server。把工作区代码目录（如 /home/gem/workspace/code）原样托管，供 agent / 浏览器经沙箱网关访问。

底层用 serve-handler（serve CLI 的引擎）兜底静态服务（文件解析 / MIME / 路径穿越防护 / Range / 条件请求），本包只做一层薄封装：剥 base 前缀 + 目录首页解析 + 关缓存 + 留扩展位。与 @lark-apaas/coding-html-devserver 零代码耦合。

用法

coding-static-server [--root <dir>] [--port <n>] [--host <addr>] [--base <path>]

| flag | 默认 | 说明 | |------|------|------| | --root | .（cwd） | 静态根目录，沙箱传 /home/gem/workspace/code | | --port | CLIENT_DEV_PORT env ‖ 8001 | 监听端口 | | --host | 0.0.0.0 | 绑定 host | | --base | CLIENT_BASE_PATH env ‖ 空 | 要剥离的前缀，如 /af/p/<appId>/ |

行为

• 剥网关前缀（正则，不依赖 env）：网关把完整路径 /app/<appId>/...（或旧形态 /af/p/<appId>/...）透传过来。本包用正则 ^/(app|af/p)/[^/]+ 识别并剥掉这层前缀，再映射到 --root 下的文件。默认不依赖 CLIENT_BASE_PATH——因为该 env 是绑定时才写入沙箱 env 文件的，进程启动（容器 boot / 池预热）时拿不到。若启动时确有 --base/CLIENT_BASE_PATH 则优先用它精确匹配。非网关前缀的路径原样透传。
• 裸 base 补尾斜杠：恰为 base 的无尾斜杠请求（/app/<appId>）→ 301 到 /app/<appId>/，Location 带完整前缀（本包自己构造，不经 serve-handler，不丢前缀）。否则页面停在无尾斜杠 URL，相对资源会解析成 /app/assets/x.js（丢 appId 段）→ 404。
• 目录首页解析：pathname 以 / 结尾补 index.html（/ → /index.html，/sub/ → /sub/index.html）。
• Clean URL（MPA 无扩展名路由）：无扩展名、无尾斜杠的 pathname 按两种约定在 root 下查 html 并重写（fs 判断 + 重写，不发 301）：/about → about.html（平铺）或 about/index.html（目录），两者都存在时优先平铺 .html。
• 命中文件零 3xx：除上面那条受控的补斜杠 301 外，命中文件不产生重定向；尤其关掉 serve-handler 默认 cleanUrls（它会把 /index.html 301 到 /index 且 Location 丢 base 前缀，网关下死循环）。
• 非 SPA：文件不存在返回 404，不做 history fallback。
• 关缓存：响应带 Cache-Control: no-store，预览改了即时生效。
• 安全：不列目录、不跟随软链。

编程接口

import { startServer } from '@lark-apaas/coding-static-server';

const server = await startServer({ root: '/home/gem/workspace/code', port: 8001, base: '/af/p/app_x/' });

亦导出 resolveConfig / resolvePrefix / stripBase / appendIndexHtml / bareBaseRedirect / cleanUrlResolve / createRequestListener / normalizeBasePath / parseFlags 供组合与测试。