XiHan.Website

曦寒（XiHanFun）官方网站源码，www.xihanfun.com。站点展示曦寒生态的三大产品——XiHan.Framework（后端基座）、XiHan.UI（前端基座）、XiHan.BasicApp（基础应用）——并链接到各自的文档、在线 Demo 与社区入口。

站点本身是 XiHan.UI 的第一个对外消费方：除 XiHan.UI 外不引任何 UI 库，也不引 CSS 框架。顶栏、抽屉、按钮、页签、代码窗与复制都来自 @xihan-ui/vue；细线网格、图编号、线描示意图与首屏点阵是站点自绘，颜色、间距与动效全部取自 @xihan-ui/tokens 的设计令牌。设计取向见 PRODUCT.md。

技术栈

• Vue（<script setup>）+ TypeScript + Vue Router
• Vite 构建，@vitejs/plugin-vue
• XiHan.UI（版本以 pnpm-workspace.yaml 的 catalog 为准）
  • @xihan-ui/vue 组件与状态机运行时
  • @xihan-ui/styles 默认皮肤 · @xihan-ui/tokens 设计令牌与主题运行时
  • @xihan-ui/icons 图标 · @xihan-ui/animations 进场动效 · @xihan-ui/code-highlight 代码着色
• 字体：拉丁字形 Archivo、等宽 JetBrains Mono，经 Google Fonts 非阻塞加载，取不到时用回退字体；中文走系统字体
• 包管理：pnpm 11 / Node 24

页面

路由	内容
/	首屏点阵、三个产品、组合方式、可信依据、上手命令、行动入口
/framework	五层模块架构、能力清单、代码示例、技术选型
/ui	包与四个角色组、设计原则、三种用法、组件总览、接入方式
/basicapp	权限三层、三根支柱、审计、模块清单、本地启动

目录结构

Website/
├── index.html               # 入口页面，含 SEO / OG / Twitter Card meta
├── src/
│   ├── main.ts               # 皮肤导入、主题运行时、挂载
│   ├── App.vue               # 站点外壳：顶栏 + 路由出口 + 页脚 + 回到顶部
│   ├── router.ts             # 四条页面路由 + 通配兜底回首页，懒加载
│   ├── theme.ts              # 主题控制器，整站共用一个实例
│   ├── highlighter.ts        # 代码着色器，整站共用一份
│   ├── components/
│   │   ├── SiteHeader.vue / SiteFooter.vue / SectionHead.vue / PageHero.vue
│   │   ├── LinkButton.vue        # 链接形态的按钮（站内走路由，外链新窗口）
│   │   ├── CodeWindow.vue        # 代码窗：页签 + 复制 + 代码视图
│   │   ├── HalftoneFigure.vue    # 首屏点阵，按 public/assets/figure.jpg 取样
│   │   ├── diagrams/             # 三个产品、组合方式与可信依据的线描示意图
│   │   ├── ThemeToggle.vue       # 顶栏色彩模式循环按钮
│   │   └── ThemeControls.vue     # 抽屉里的色彩模式分段控件
│   ├── composables/reveal.ts     # v-reveal 滚动进场指令
│   ├── data/                     # 站点文案与清单（产品、分层、包、模块）
│   ├── pages/                    # 四个页面
│   └── styles/site.css           # 站点自有样式，收在 @layer site
├── scripts/spa-fallback.mjs   # 构建后把 index.html 复制成 404.html
├── public/                    # 静态资源，原样拷贝到 dist（含 CNAME）
├── vite.config.ts
└── .github/workflows/deploy-website.yml

样式层的两条约定

1. 站点样式收在 @layer site。它在 @xihan-ui/styles 之后引入，所以排在 xihan.* 全部子层之后，站点规则天然压得住皮肤。
2. 全局元素重置一律带 :not([data-scope])。站点层排在皮肤之后，裸的 a {} / button {} 会连库节点一起命中并压掉皮肤；这个否定选择器把库的部件让出去。

main.ts 只引 @xihan-ui/styles 一个入口，不再单独引一次 tokens.css——皮肤入口第一句就是层序声明、第二句才是令牌，顺序由它保证；抢在它前面引令牌会让 xihan.tokens 先注册，把层序拧了。

本地开发

pnpm install
pnpm dev

构建与预览

pnpm run build

依次跑三步：vue-tsc --noEmit 类型检查 → vite build 出 dist/ → scripts/spa-fallback.mjs 生成 dist/404.html。

pnpm run preview

部署

推送或提交 PR 到 main 分支时，GitHub Actions（.github/workflows/deploy-website.yml）会自动安装 Node 与 pnpm（版本以工作流为准）、pnpm install --frozen-lockfile、pnpm run build，再通过 JamesIves/github-pages-deploy-action 把 dist/ 部署到 gh-pages 分支。

三个与 GitHub Pages 有关的细节，缺一个站点就是坏的：

• public/.nojekyll：Pages 默认跑 Jekyll，而 Jekyll 会把 _ 开头的文件当源文件排除在产物之外。Vite 的共享分片里有一个 _plugin-vue_export-helper-*.js，没有这个空文件它就会 404，懒加载的路由分片跟着整片挂掉——表现是页头页脚正常、正文空白。这个文件不能删。
• public/CNAME：自定义域名 www.xihanfun.com 随 dist/ 一并发布。放在仓库根目录的那一份不会进产物。
• dist/404.html：Pages 是静态托管，直接访问 /framework 这类深链接会落到 404；构建后把 index.html 复制一份成 404.html，Pages 拿它兜底，路由再交回前端。

License

MIT © 2021-Present XiHanFun and contributors.