Valaxy 1.0：从写作体验到构建内核

Valaxy 1.0 正式发布了。你仍然可以从一篇 Markdown 开始，在需要交互时加入 Vue 组件，最后把站点生成静态文件。这个版本把写作、管理、渲染和扩展进一步连接起来：日常维护有了更完整的工具，构建使用统一的渲染路径，图表和音乐等功能则按需安装。

这篇文章解释这些变化对博客作者、主题开发者和插件作者分别意味着什么。

从写一篇文章开始 ​

Valaxy 的内容仍保存在项目文件中。文章可以使用 Markdown 描述文字、图片和代码，也可以直接引用 Vue 组件。需要一个交互示例、计算器或自定义卡片时，可以把组件和文章一起维护，并在开发服务器中预览。

内容与外观也有各自的位置。site.config.ts 描述站点信息，valaxy.config.ts 配置主题、插件和框架行为；主题负责布局与视觉。Yun 面向个人博客，Press 提供文档导航、侧边栏和内容组织方式。本网站的文档与博客就在同一个 Press 站点中。

这让写作流程可以逐步扩展：先完成文章，再根据内容需要增加组件、选择主题或接入插件。已有 Markdown、图片和 Git 历史仍然是项目的一部分。参阅文章指南与在 Markdown 中使用 Vue。

日常管理有了可视化入口 ​

在开发模式中，Valaxy DevTools 将文章、配置和插件管理放进 Vite DevTools 面板。你可以浏览文章、调整元信息、管理分类与标签，再将修改保存回项目文件。调试页面可以查看当前路由和 Frontmatter，帮助定位“这个页面为什么使用这个布局”等问题。

插件管理也区分了几种状态：浏览插件、安装依赖、在配置中启用插件，是不同的操作。安装成功后仍需按照插件文档配置，涉及依赖或配置变更时先查看预览。这样更容易理解一次管理操作会改动哪些文件。

DevTools 随开发服务器运行，生产构建不包含这个管理面板。编辑器用户可以选择 VS Code 扩展，偏好桌面写作的用户可以了解云栈公开预览。这些入口围绕同一份项目内容工作，具体支持范围以各自文档为准。

构建流程收敛到一套实现 ​

1.0 的构建底座是 Vite 8 与 Rolldown。开发时仍然使用热更新查看文章、组件和配置变化；发布时由构建流程生成浏览器资源，再通过 Vue SSR 生成静态页面。

旧的 JSDOM vite-ssg 引擎已经移除，现在使用内置 Valaxy SSG 引擎，以 Vue SSR 和字符串处理完成页面输出。构建时不再通过模拟 DOM 提供 window、document 或 navigator。主题和插件应将依赖浏览器的操作放到客户端执行；只在本地开发预览中正常工作，还不足以确认静态构建兼容。

这也改变了首屏样式的处理方式。1.0 移除了 Critical CSS 内联，使用 FOUC guard 协调首次显示与样式就绪。SSG 负责生成 HTML，CSS 仍按构建产物加载；不能因为站点使用 SSG，就推断样式全部内联或没有额外请求。关于浏览器专属组件与水合问题，见 SSR 兼容性。

构建工具的变化也会影响自定义配置。旧的 Rollup manualChunks 示例不应直接当作当前框架实现；Valaxy 已使用 Rolldown 的 codeSplitting 配置。实际耗时与资源大小取决于内容、主题、插件、机器和缓存状态，需要在自己的站点上测量。

正文、摘要和订阅源共用异步渲染语义 ​

一篇文章会出现在多个地方：详情页展示正文，列表页显示摘要，搜索提取可检索文本，RSS 向订阅者提供内容。它们都需要处理 Markdown，异步代码高亮等步骤也需要被正确等待。

1.0 将这些处理路径放在统一的异步渲染语义下。Shiki 在需要时异步加载语言，同一配置下可以复用高亮实例。这样，插件作者可以围绕统一的渲染约定工作，减少某条内容输出路径仍假设渲染同步完成的问题。

“统一语义”并不意味着几个出口的结果完全相同：摘要会截取内容，搜索会提取文本，订阅源还需要处理链接；浏览器中的交互组件也不能原样变成 RSS 中的交互。自定义 Markdown 扩展时，应同时检查正文、摘要和自己使用的内容出口。扩展语法见 Markdown 指南。

核心、主题与插件各自承担职责 ​

Mermaid 图表和 Meting 音乐播放器在 1.0 中通过独立插件提供。需要这些功能的站点安装并启用对应插件；已有内容则按迁移指南调整。Mermaid 的 Markdown 代码块可以继续使用，旧的音乐播放器开关需要迁移。

对作者而言，这意味着启用功能时需要关注插件安装和配置。对维护者而言，图表、播放器等集成有了各自的依赖与发布位置，可以围绕明确的功能范围维护。插件的体积、第三方脚本和服务需求仍需结合具体插件判断。

除了图表和音乐，还可以按需加入评论、搜索、相册或 Moments 短内容时间线。完整清单与使用方法见官方插件。

AI 可以查询框架如何理解文章 ​

AI 助手可以直接读写项目里的 Markdown。Valaxy 提供的额外信息，是框架解析之后的结果：最终路由是什么、使用哪个布局、是否为草稿，以及本地链接可能存在什么问题。路由和元数据受到配置或钩子影响时，只阅读源文件未必能得到这些答案。

1.0 的本地 MCP 服务默认关闭，开启后提供只读的查询、阅读与检查工具，不通过 MCP 创建或修改文章，也不执行管理操作。DevTools 的可视化编辑能力与这个服务分别配置，生产站点不会包含本地 MCP 服务。

不接入 MCP 也可以使用命令行检查，例如在博客目录执行：

pnpm exec valaxy inspect --file pages/posts/hello.md --json
pnpm exec valaxy check --file pages/posts/hello.md --json

将路径替换为自己的文章。它们可以帮助作者或编程助手确认编辑后的解析结果；完整构建仍然负责验证发布流程。连接方式与可见内容范围见与 AI 协作。

升级时按自己的使用范围检查 ​

从旧版本升级前，先保存项目与依赖锁文件，并确认本地和部署环境使用 Node.js 22.12.0 或更高版本。随后按站点的实际功能检查：

主题开发者尤其需要检查生产构建。路由直达、手机布局、弹层和交互组件都应在静态预览中确认；运行时表现不能仅从配置文件推断。

逐项操作请使用完整迁移指南。如果是第一次使用 Valaxy，可以从快速开始创建站点，或先浏览 1.0 发布专题，看看 Markdown、主题与 DevTools 如何配合。