Vuepress on Howar31 Blog

升上 VuePress v2 RC 五個月後，決定再遷移到 Hugo 的紀錄

Wed, 22 Apr 2026 00:00:00 +0000

前言

2025 年 11 月才剛從 VuePress v1.8 升上 v2.0.0-rc.26，本以為至少能安穩用個幾年。結果升完五個月就遇到一堆問題，最後在 2026 年 4 月決定再搬一次，這次換到 Hugo。

這篇記錄從評估、選型、遷移、踩雷到最後部署上線的完整過程，順便也拿這篇當 component 測試文，把 Hugo 版型的 code block、tip、warning、表格、SVG、taxonomy 一次全部跑過。

為什麼升 v2 才 5 個月就要再搬？

升級前以為是一次「大幅刷新但之後穩定」的投資。升完才真正理解現狀：

VuePress v2 本身自 2022 就卡在 RC，到 2026 仍然沒有 stable。這個「卡 RC 3+ 年」的背景是在升上去之後才有切身感受
插件生態沒跟上：v1 時期依賴的若干插件在 v2 沒有對應版本，有些甚至上游直接放棄維護
RC 階段的 theme API 仍會 breaking change：升 v2 時已經改了一次 theme，完全不想再因為某次 RC 升級又全部改一次
Dev server 啟動 30 秒：寫文章的摩擦大到開了就忘記要寫什麼

與其繼續賭 v2 什麼時候脫 RC，不如直接換到生態穩定、建置極快的工具。於是評估了 Astro、Next.js、Eleventy、Hugo，最後選 Hugo：

候選	建置速度	生態穩定度	Runtime 依賴	主要缺點
Hugo	極快（幾百毫秒）	十年以上穩定	Go binary	模板語法較陌生
Astro	中等	快速演進中	Node.js	還在 breaking changes
Next.js	慢（依頁面數成長）	成熟但偏 App	Node.js	對靜態部落格 overkill
Eleventy	快	小眾但穩定	Node.js	template 選擇多到雜亂

Hugo 的勝出原因很簡單：Go 寫的單一執行檔、零 Node.js、零 npm、template 語法雖然怪但至少不會自己 breaking change。

從 VuePress v1 升級到 v2

Sun, 23 Nov 2025 00:00:00 +0000

使用 VuePress v1 架設 blog 好幾年了，我決定升級到 VuePress v2，主要是想用更現代的建置系統、更好的效能，還有更好的開發體驗。 VuePress v2 帶來了不少改進，包括 Vite 打包工具、Vue 3 支援、TypeScript 支援，還有更模組化的插件架構。

這篇文章記錄了我從 VuePress v1 升級到 v2 的過程，包括遇到的問題和解決方法。

為什麼要升級？

VuePress v2 有幾個讓我想要升級的理由：

Vite 打包工具 - 建置時間比 webpack 快很多，熱模組替換也更快
Vue 3 支援 - 現代的 Composition API 和更好的效能
TypeScript 支援 - 型別安全的配置和更好的 IDE 支援
模組化架構 - 更好的插件系統和更靈活的客製化
效能改進 - 優化的打包分割和更快的頁面載入
更好的開發體驗 - 改進的錯誤訊息和除錯工具

Tip

寫這篇文章的時候，VuePress v2 還在 Release Candidate (RC) 階段 (v2.0.0-rc.26)，不過已經穩定到可以上 production 了。官方 v2 正式版應該很快就會發布。

環境

升級時使用的環境：

Setup VuePress with GitLab Pages on Ubuntu 18.04 LTS

Wed, 17 Apr 2019 00:00:00 +0000

This is a lite version of setup tutorial about Vuepress docs on Ubuntu. For detailed tutorial I wrote, please visit Create a docs with VuePress on GitLab Pages.

Environment

Ubuntu 18.04.1 LTS
Node.js 11.14.0
npm 6.9.0

Setup VuePress

VuePress Official Guide

Install VuePress

First, install VuePress globally:

npm install -g vuepress

or if you want to install locally:

npm install vuepress

Warning

With Vuepress installed locally, you may need to use npx vuepress in command line.

Config Build Path for GitLab Pages

To change the built files destination, we must set it up in config file. By default the config file is not exist, you may create a config file by yourself:

Enable PWA Support for VuePress

Fri, 22 Mar 2019 00:00:00 +0000

PWAs, Progressive Web Applications are web applications which is loaded as a website, but can also provide native app functionalities, such as offline mode, push notification, hardware access, and more. For more info about PWA, please read the articles metioned in References.

Environment

The environment I used:

macOS Mojave, 10.14.3
VuePress 0.14.10

I setup my blog as a PWA successfully. You may visit my blog on your phone (Chrome on Android recommended) to see how it works.

Create a Blog with VuePress on GitLab Pages

Wed, 20 Mar 2019 00:00:00 +0000

After several years hosting my blog on Wordpress, I decided to move my blog to VuePress so that I may write my blog with Markdown, and also customize my blog with Vue.js.

VuePress is a Vue-powered static site generator, which can easily help you to setup a SPA website in just few minutes. And with CI/CD and GitLab Pages integration, it becomes one of the best solution for personal blog which can be programmatically themed with Vue.js, automatically publish with CI/CD, and free host with GitLab Pages.

Thanks Wordpress, Hello VuePress

Mon, 18 Mar 2019 13:00:00 +0000

Welcome, Howar31 Blog is moved again! We are now on GitLab Pages + VuePress.

New Blog in 2019

After hosting blog on Wordpress for several years, I found that it’s very hard and complicated to maintain the blog, since there are so many plugins and themes to take care of. Moreover, writing in HTML (rich editor) is not my type. I’d love to write docs in Markdown due to simplicity and efficiency. These reasons make me want to move my blog to a new home.