桌面应用【免费下载链接】QOwnNotesQOwnNotes is a plain-text file notepad and todo-list manager with Markdown support and Nextcloud / ownCloud integration.项目地址https://gitcode.com/gh_mirrors/qo/QOwnNotes点击查看免费下载本文以 QOwnNotes 项目仓库中发布的 改版公告文档 为主体结合 webpage 目录下的真实源码、配置与测试系统拆解这次官网重构的动机、技术选型、站点架构与工程实践。读完你将掌握VuePress 2 与 Vue 3 时代如何组织多语言静态站点、Vuetify 3 如何与 VuePress 客户端入口协同、博客内容流水线与 SEO/Feed 插件如何配置以及基于 Playwright 的端到端测试和 Docker/nginx 部署流水线是如何落地的。为什么需要这次改版QOwnNotes 官网承载产品文档、安装指南、脚本 API 文档与官方博客此前长期运行在VuePress 1之上。随着 Web 技术生态的演进VuePress 1 已经进入生命周期终点end of life不再获得维护与安全更新因此向下一代框架迁移既是必要的技术升级也是一次时机合适的整体翻新。这次改版是 QOwnNotes 项目的第 #3414 号工作项见公告原文的直接产出核心目标有三让站点跟上现代前端技术栈、改善性能与可访问性、为读者提供更现代的使用体验。新版技术栈概览公告文档给出了新官网的依赖全景{ vuepress: next (v2.x), vue: ^3.x (via VuePress 2), vuetify: ^3.7.4, vuepress/bundler-vite: next, vuepress/plugin-docsearch: next, vuepress/plugin-feed: next, vuepress/plugin-seo: next, vuepress/plugin-sitemap: next }对照仓库中的 webpage/package.json 可以看到实际锁定版本比公告更进一步vuetify已推进到3.11.5vuepress、vuepress/bundler-vite及 docsearch、feed、seo、sitemap 等官方生态插件均以nextv2 分支版本引入并额外加入了Markdown 增强插件族vuepress/plugin-markdown-chartMermaid 图表、markdown-container、markdown-ext任务列表、markdown-hint、markdown-stylize主题与样式工具vuepress/theme-default、sass、mdi/fontMaterial Design 图标字体、vuepress-plugin-md-enhance内容与测试设施markdown-itmarkdown-it-metafrontmatter 元数据解析、date-fns日期格式化、mermaid、playwright/test与playwright-core版本1.57.0。VuePress 2构建与插件体系的代际升级公告将 VuePress 2 的优势概括为五点Vite 驱动的打包带来更快的构建速度与开发期热更新HMR更完善的插件系统提升可扩展性与可维护性增强的 Markdown 支持带来更好的语法高亮与扩展能力更好的 TypeScript 支持以及优化后的生产构建代码分割与懒加载。这些特性在仓库配置中有直接落点。webpage/src/.vuepress/config.js 中通过defineUserConfig显式选择viteBundler作为打包器并做了三处针对 SSR 与静态产物的关键调优// 关闭 SSR 预加载规避 CSS 导入问题 shouldPreload: false, shouldPrefetch: false, bundler: viteBundler({ viteOptions: { ssr: { noExternal: [vuetify], // 让 Vuetify 参与 SSR 编译 }, build: { rollupOptions: { output: { // 关闭资源文件名的 hash 后缀输出固定 assets/ 目录 assetFileNames: ..., }, }, }, }, }),从源码结构看这三项配置分别解决Vuetify 组件在服务端渲染时无法外部化的兼容问题、静态资源路径稳定性利于 CDN 与缓存策略以及预加载对页面首屏的干扰。这正是公告中“Vite 打包 优化生产构建”的实际工程体现。Vue.js 3以 Composition API 重写自定义组件公告指出 Vue 3 带来的核心收益包括Composition API更灵活、可复用的组件逻辑、更快的虚拟 DOM 与响应式系统、通过 tree-shaking 与优化运行时实现的更小包体积、原生 TypeScript 支持以及更好的开发者体验。Vue 3 的能力直接作用于站点客户端运行时。webpage/src/.vuepress/client.ts 是 VuePress 2 的客户端入口它做了三件事创建并挂载 Vuetify 实例通过createVuetify({ components, directives, theme: { defaultTheme: light } })组装 Vuetify并在app.use(vuetify)中注册站点内的v-*组件如v-snackbar、v-chip、v-carousel、v-icon全部由此驱动全局注册自研组件Poll用户调查浮层、RssBlockRSS 订阅入口、BlogDate博客日期、BlogIndex博客列表、ProfileCard、ScreenshotCarousel截图轮播六个组件通过app.component(...)全局可用以原生脚本替代插件实现 Matomo 埋点原先的vuepress-plugin-matomo被移除改在enhance钩子中手动初始化window._paq并通过router.afterEach在 SPA 路由切换时同步上报自定义 URL 与标题。其中Poll.vue、RssBlock.vue、ScreenshotCarousel.vue等组件大量使用script setup组合式语法与computed、ref、onMounted、nextTick等 Composition API是 Vue 3 新编程模型在真实站点中的典型示范。Vuetify 3Material Design 3 与可访问性公告将 Vuetify 3 的价值归纳为Material Design 3 组件、更强的 ARIA 与键盘导航支持、全尺寸响应式布局、基于 CSS 变量的可定制主题以及更丰富的组件库。仓库中的证据包括ScreenshotCarousel.vue 使用v-carouselv-carousel-item构建官网首页截图轮播并通过onMountednextTick 延迟挂载规避 SSR 时序问题Poll.vue 使用v-snackbar、v-text-field、v-btn构建底部调查问卷提交后通过window._paq.trackEvent上报到 MatomoLayout.vue 在页脚使用v-iconmdi-github、mdi-mastodon渲染社交图标styles/index.scss 中针对 Vuetify 的全局 reset 做了补偿p, ul, ol { margin: 16px 0; }并为阿拉伯语、波斯语等 RTL 语言补齐完整的镜像布局规则——这正是“响应式 可访问性 可定制主题”在真实站点上的落地。值得留意的是Vuetify 与 VuePress 的结合存在 SSR 兼容问题仓库通过ssr.noExternal: [vuetify]见 config.js将 Vuetify 纳入 SSR 编译链解决Dockerfile 中甚至保留了一段被注释的patch-vuetify-ssr.sh补丁脚本作为备选方案可见官方团队在集成过程中做过反复验证。多语言站点架构改版后的官网是一套11 语种的多语言静态站点。VuePress 的locales配置在 config.js 中声明了/英语、/de/、/it/、/fr/、/es/、/fa/、/nl/、/hu/、/ar/、/pl/、/ko/共 11 个语言目录每个语言分别维护独立的导航栏navbar与侧边栏sidebar文案。侧边栏的自动生成由 utils.js 完成getChildren用globSync扫描src/**/*.md通过markdown-it-meta读取每篇文档 frontmatter 中的order字段再按order与path排序输出导航项getBlogChildrenWithTitles则在博客侧边栏中提取每篇文章的 H1 标题作为显示文本。也就是说调整文档顺序只需改 frontmatter 的order值无需手工维护导航清单。RTL 语言阿拉伯语、波斯语的排版由 styles/index.scss 中的html[dirrtl]规则统一处理涵盖侧边栏、代码块、页码导航、搜索框等全部布局的镜像翻转。博客内容流水线博客是本次改版的重点场景之一其内容管理链路值得单独梳理元数据声明每篇博客以---frontmatter 声明title、description、image、date、order例如本文依据的改版公告即位于 webpage/src/blog/2025-12-30-QOwnNotes-Webpage-Relaunch-with-VuePress-2-Vue-3-and-Vuetify-3.md索引生成generate-blog-data.js 在开发启动与生产构建前自动运行扫描src/blog/**/*.md从文件名提取YYYY-MM-DD日期、从 frontmatter 提取标题与描述生成src/.vuepress/blog-data.json该文件被 git 忽略、每次构建重新生成列表渲染BlogIndex.vue 读取blog-data.json渲染文章列表BlogDate.vue 负责将 frontmatter 中的日期统一格式化为yyyy-MM-ddFeed 输出feedPlugin同时开启rss、atom、json三种格式输出rss.xml、feed.atom、feed.json并通过filter限定只收录blog/目录下的文章按日期倒序排列。这条链路让博客作者只需维护 Markdown 文件本身索引、列表、订阅源全部自动化生成。SEO 与站点元信息改版对搜索引擎与社交分享的投入体现在 config.js 的插件组合上DocSearchAlgoliadocsearchPlugin配置了appId、apiKey、indexName: qownnotes并为全部 11 种语言提供了搜索框占位符与按钮文案的本地化翻译实现全站文档搜索SEO 插件seoPlugin设定hostname与canonical并通过ogp回调为每篇博客生成 Open Graph 与 Twitter Card 标签og:image、twitter:card: summary_large_image、twitter:creator等图片地址优先取 frontmatter 中的image字段Sitemap 插件sitemapPlugin生成sitemap.xml并排除404.htmlhead 元信息包括theme-color、apple-mobile-web-app系列、favicon、Material Design 图标字体 CDN 以及 RSS 订阅入口。对应的端到端断言可在 tests/head-tags.spec.js 中看到测试逐项校验 meta description、og:title、twitter:card、favicon、三种 Feed 链接与relme社交验证链接tests/algolia.spec.js 则验证首页、概述页与博客页的搜索弹窗可正常唤起。端到端测试与质量保障公告将“用 Playwright 实现全面的端到端测试”列为改版工作之一仓库中的测试设施非常完整playwright.config.js 定义了Chromium 与 Firefox 双浏览器测试项目并针对 CI 环境自动放大超时timeoutMultiplier 3、启用失败重试CI 下 2 次若环境未提供CHROMIUM_BIN/FIREFOX_BIN会在启动阶段自动下载安装浏览器config.js 通过TEST_ENV环境变量切换测试目标支持prodwww.qownnotes.org、nextnext.qownnotes.org、locallocalhost:8080与local-dockerlocalhost:8081四套环境fixtures.js将其注入 Playwright fixturepackage.json 提供playwright:test系列命令并区分--ui交互模式与local/next/local-docker环境变体。测试用例覆盖五个维度页面可达性与标题basic.spec.js、博客列表结构与具体文章渲染blog.spec.js、SEO 头部标签head-tags.spec.js、Matomo 埋点请求是否真实上报且携带idsite与url参数matomo.spec.js、RSS/Atom/JSON Feed 结构与内容rss.spec.js、sitemap 可访问性sitemap.spec.js以及多语言页面的导航、正文与lang属性translations.spec.js另有 mermaid、carousel、survey-popup 等专项测试。构建与部署流水线新站点的工程化部署链路分为开发、构建、容器化三层开发启动npm run dev调用 run-dev.sh该脚本依次完成三项预处理——把../screenshots截图与根目录CHANGELOG.md拷贝进 VuePress 的public资源目录、运行node scripts/generate-blog-data.js生成博客索引、最后以npx vuepress dev src启动开发服务器默认http://0.0.0.0:8080/。按 webpage/README.md 的说明源码修改会自动热更新到页面。生产构建npm run build产出静态站点到webpage/src/.vuepress/dist构建脚本在 package.json 中声明为./scripts/run-build.sh。容器化部署多阶段 Dockerfile 以node:22-alpine为构建基座通过npm ci依据 lockfile 精确安装依赖构建完成后将src/.vuepress/dist拷贝进nginx:latest同时写入org.flathub.VerifiedApps.txt的 Well-Known 校验文件docker-compose.yml 提供dev8080 端口开发服务与web8081 端口生产站点容器名qownnotes-webpage两个服务。反向代理nginx.conf 承担三件事把qownnotes.org/docs.qownnotes.org301 跳转到www.qownnotes.org用map规则将旧版站点的历史 URL如/changelog/QOwnNotes、/en/latest/...文档路径重定向到新版对应页面避免链接失效将/api/与rss/project_version反向代理到qownnotes-api后端。此外 justfile 提供了dev、build、clean、install、playwright-test等一组便捷命令。小结这次官网改版不是一次简单的脚手架升级而是一次围绕VuePress 2 Vue.js 3 Vuetify 3的体系化重建以 Vite 打包与 Vue 3 Composition API 重构站点运行时以 Vuetify 3 统一视觉与交互以 11 语种 locales 与 RTL 样式支撑国际化以 frontmatter 驱动的流水线管理博客内容以 DocSearch/SEO/Sitemap/Feed 插件完善站点曝光再以 Playwright 双浏览器端到端测试与 Docker nginx 流水线保障发布质量。对于计划将存量 VuePress 1 站点迁移到 VuePress 2、或希望在同一套技术栈下搭建多语言文档站 博客的团队QOwnNotes 官网的这份源码实现是一份相当完整、可直接参照的工程范本。赞分享桌面应用【免费下载链接】QOwnNotesQOwnNotes is a plain-text file notepad and todo-list manager with Markdown support and Nextcloud / ownCloud integration.项目地址https://gitcode.com/gh_mirrors/qo/QOwnNotes点击查看免费下载相关推荐QOwnNotes 官网前端实战基于 VuePress 2 的网页开发、构建与自定义指南QOwnNotes 官网前端实战基于 VuePress 2 的网页开发、构建与自定义指南 QOwnNotes 官方网页qownnotes.org由仓库 w桌面应用SoundSwitch 官网架构与维护指南VuePress 2 文档站与 Cloudflare Workers 全栈实践SoundSwitch 官网架构与维护指南VuePress 2 文档站与 Cloudflare Workers 全栈实践 SoundSwitch 是一个用 C桌面应用用 Claude Code Action 让文档追着代码跑文档自动更新与代码同步的实操笔记用 Claude Code Action 让文档追着代码跑文档自动更新与代码同步的实操笔记 改完 API 之后README 里的接口文档还挂着旧参数两周后桌面应用开发工具上一篇RPCS3 汉化补丁 3 步安装指南让 PS3 游戏秒变中文下一篇3个颠覆性理由为什么你的下一个看板必须是Nullboard创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考