前端后端CLISSR【免费下载链接】valaxy Next Generation Static Blog Framework (Beta) 下一代静态博客框架支持页面/配置热重载项目地址https://gitcode.com/YunYouJun/valaxy点击查看免费下载刚上手 Valaxy下一代静态博客框架时很多人会被项目里的几个配置文件搞晕到底哪些设置写在哪里为什么改了一个字段却看不到效果其实答案很简单——Valaxy 的站点配置只分三层site.config.ts管「站点信息」、valaxy.config.ts管「框架与主题」、theme.config.ts管「主题外观」。本文带你快速搞懂这两大核心配置文件的每个字段并充分利用 TypeScript 类型提示让编辑器成为你的「配置说明书」。上图是默认 Yun 主题渲染出的站点首页——顶部一排社交图标、中间的站点标题与副标题全部由site.config.ts中的配置驱动。三分钟理清配置文件分层结构Valaxy 把配置拆成三个文件各司其职互不干扰配置文件职责典型字段site.config.ts站点信息与主题无关title、author、social、searchvalaxy.config.ts框架主入口主题、插件、构建theme、addons、build、markdowntheme.config.ts当前主题的外观banner、nav、footer分层的好处是换主题时站点信息完全不用动而改站点名称、作者头像时也不会碰框架配置。完整字段定义packages/valaxy/types/config.ts官方配置文档docs/pages/guide/config/index.md演示站配置示例demo/yun/site.config.ts、demo/yun/valaxy.config.tssite.config.ts站点信息一站配齐site.config.ts通过defineSiteConfig导出所有字段都是「可选的」——不写就用默认值默认值集中定义在 packages/valaxy/node/config/site.ts#L9-L127。一键设置站点基础信息最常用的字段如下建议第一次配置就填好lang/languages默认语言与可选语言列表。想让站点只支持中文设为[zh-CN]即可关闭多语言切换title/subtitle/description站点标题、副标题、描述直接影响浏览器标签页和 SEOtimezone时区国内博客推荐Asia/Shanghai用 CI 部署时尤其重要避免文章时间漂移url站点完整 URLSSG 与 RSS 生成文章永久链接时必需author作者信息包含name、avatar、email、intro等社交图标与搜索功能social字段是站点「门面」每一项包含name名称、link链接、icon图标名支持 Iconify 图标名、color颜色export default defineSiteConfig({ lang: zh-CN, timezone: Asia/Shanghai, social: [ { name: RSS, link: /atom.xml, icon: i-ri-rss-line, color: orange, }, ], // 开启本地搜索 search: { enable: true, provider: fuse }, })search.provider支持四种方案algolia云端搜索、engine跳转搜索引擎、fuse与local两种纯本地搜索新手推荐零成本的fuse。按需开启的功能开关site.config.ts还提供了一批「一键开关」每个都可以单独启用mediumZoom: { enable: true }图片点击放大预览vanillaLazyload图片懒加载增强statistics: { enable: true }文章字数与阅读时间统计encrypt文章内容加密支持整篇或局部加密orderBy: date | updated文章列表按创建时间或更新时间排序redirects客户端路由重定向规则更细致的字段如license、excerpt、codeHeightLimit、llms全部可以在类型定义中查到packages/valaxy/types/config.ts#L44-L493。valaxy.config.ts框架主入口valaxy.config.ts是整个项目的配置总入口通过defineValaxyConfig导出。官方推荐的写法参考 demo/yun/valaxy.config.tsimport type { ThemeConfig } from valaxy-theme-yun import { defineValaxyConfig } from valaxy import { addonMermaid } from valaxy-addon-mermaid export default defineValaxyConfigThemeConfig({ // 站点信息写在 site.config.ts 中这里不需要重复 theme: yun, build: { ssgForPagination: true }, addons: [addonMermaid()], })几个新手最需要知道的核心字段theme主题名称不写默认就是yun解析逻辑见 packages/valaxy/node/config/valaxy.ts#L179themeConfig也可以直接把主题配置写在这里与theme.config.ts二选一addons插件系统Mermaid 图表、评论、相册等功能都以插件形式挂载markdown代码高亮主题、容器tip/warning文案定制build构建选项比如ssgForPagination预生成分页静态页unocssUnoCSS 配置可加safelist保留动态图标vite透传 Vite 配置可加 PWA 等插件提示devtools: true默认开启会启动 Valaxy DevTools如上图所示可以直接在浏览器里管理文章元数据排查配置问题时非常顺手。类型提示详解让编辑器替你写文档这是 Valaxy 配置最省心的一点每个字段都带中文注释鼠标悬停就能看到完整说明。实现原理是defineSiteConfig/defineValaxyConfig是「类型助手函数」本身不做任何处理只为参数提供精确类型分别见 packages/valaxy/node/config/site.ts#L133-L135 与 packages/valaxy/node/config/valaxy.ts#L120-L123用户配置类型基于PartialDeep深层可选工具类型生成packages/valaxy/types/config.ts#L495-L497所以每个字段——包括嵌套字段——都可以省略defineValaxyConfigThemeConfig的泛型参数用来关联具体主题的类型。比如传valaxy-theme-yun导出的ThemeConfig后themeConfig里的banner、nav等字段同样拥有完整的自动补全实际体验是输入theme: 会提示可用主题输入search.provider会列出algolia | engine | fuse | local拼错字段名直接标红。配置即文档基本不用查资料。新手常见坑与最佳实践✅一个文件只放一类配置站点信息进site.config.ts框架与插件进valaxy.config.ts主题外观进theme.config.ts维护时一目了然✅善用$t()做国际化像演示站那样用$t(siteConfig.title)引用翻译文本中英文站点一套配置通吃示例见 demo/yun/site.config.ts#L13-L24✅只写差异不写默认值所有未配置的字段都会与默认值自动合并配置文件越短越好⚠️改配置后等热重载Valaxy 支持页面/配置热重载修改配置文件后会自动重启生效控制台会打印Resolve siteConfig from ...的提示⚠️url别漏配只写title不写url时RSS 和 SSG 的绝对链接会失效⚠️主题字段要看对应主题的类型themeConfig的字段由所选主题决定换主题时编辑器报错就是提示你删掉了不适用的字段快速上手清单用site.config.ts配好title、author、timezone、social四项基础信息用valaxy.config.ts指定theme并挂载需要的addons编辑器悬停任意字段查看中文说明按需追加search、statistics等功能对照官方文档 docs/pages/guide/config/index.md 与演示配置 demo/yun/site.config.ts 查漏补缺掌握这套「分层配置 类型提示」的工作流后Valaxy 的配置文件不再是黑盒而是一份会自我解释的说明书。赞分享前端后端CLISSR【免费下载链接】valaxy Next Generation Static Blog Framework (Beta) 下一代静态博客框架支持页面/配置热重载项目地址https://gitcode.com/YunYouJun/valaxy点击查看免费下载相关推荐EmDash 站点配置完全指南从 astro.config.mjs 到类型生成EmDash 站点配置完全指南从 astro.config.mjs 到类型生成 EmDash 是基于 Astro 构建的全栈 TypeScript CMS站CMS后端前端插件系统EmDash 站点配置完全指南从 astro.config.mjs 到类型生成EmDash 站点配置完全指南从 astro.config.mjs 到类型生成 本篇指南以 EmDash 官方 starter cloudflare 模板自带CMS后端前端插件系统EmDash CMS 站点配置完全指南从 astro.config.mjs 到类型生成EmDash CMS 站点配置完全指南从 astro.config.mjs 到类型生成 本篇指南围绕 EmDash基于 Astro 的全栈 TypeScriCMS后端前端插件系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考