部署

Valaxy 的部署非常简单，我们推荐你直接通过第三方的 CI 构建并托管到任意平台。

自行部署 ​

pnpm run build

yarn build

npm run build

执行 build 命令构建，dist 文件夹为构建后的内容。

SSG 会遵守 Node 的堆内存限制。在总内存为 4 GiB 的构建环境中，可先将堆设为 1.5 GiB，为打包器和其他进程留出空间：

NODE_OPTIONS=--max-old-space-size=1536 pnpm build

部署到子路径 ​

当站点部署在域名的子路径下时，请配置 Vite 的 base，并保留开头和结尾的 /。siteConfig.url 表示站点的规范 URL，不能代替资源路径的 base。例如，GitHub Pages 项目站点 https://user.github.io/repo/ 应配置为：

import { defineValaxyConfig } from 'valaxy'

export default defineValaxyConfig({
  siteConfig: {
    url: 'https://user.github.io/repo/',
  },
  vite: {
    base: '/repo/',
  },
})

从 Valaxy v1.0.0-rc.4 开始，这部分行为默认与 VitePress 对齐，不需要额外开启兼容开关。Vite 最终解析出的 base 会共享给页面、摘要/路由和本地搜索使用的 Markdown 渲染器。

Markdown 中的根绝对链接和静态资源会自动适配 base：

[指南](/guide/)
![Logo](/logo.png)
[下载 PDF](/manual.pdf)

Vue 组件或主题配置中的动态 URL 请使用 withBase()：

<script setup lang="ts">
import { withBase } from 'valaxy'

const logo = '/logo.png'
</script>

<template>
  <img :src="withBase(logo)" alt="Logo">
</template>

Markdown 页面与文件链接会直接补上 base；Markdown 图片则会进入 Vue/Vite 静态资源处理链路，由它在最终产物中为根绝对 public 资源应用 base。

外部 URL 和相对路径不会被修改。原生 HTML <a> 链接也保持原样，以便显式链接到 base 之外的位置；原生 HTML 图片仍可能由 Vue/Vite 转换。

页面地址 ​

pages/posts/hello.md 会写成 dist/posts/hello.html。规范地址不带末尾斜杠：/posts/hello。构建会在 sitemap 生成之后，把同一份 HTML 复制到 dist/posts/hello/index.html，这样会按目录索引查找的静态托管也能用 /posts/hello/ 打开同一页。sitemap 只记录规范地址一次。页面里的 canonical 指向不带末尾斜杠的地址。

pages/about/index.md 对应目录地址 /about/（在会把目录索引映射到短地址的托管上，/about 同样可用）。pages/404.md 会构建为 404.html，供托管商对未知路径返回。/404 不会进入 sitemap。

开发服务器里，同一条路由也接受末尾斜杠。多出来的 index.html 是为了静态部署之后这条地址仍然可用，包括那些在客户端路由运行之前就用 404.html 响应未知路径的托管。

第三方部署 ​

GitHub Pages ​

name: GitHub Pages

on:
  push:
    branches:
      # The branch where the project source code resides
      # 项目源代码所在的分支
      - main
      - master
      - valaxy
  workflow_dispatch:

# Publish the built site with GitHub Pages. The workflow token can read
# the repository and upload the artifact.
permissions:
  contents: read
  pages: write
  id-token: write

# One deployment at a time. Let an in-progress production deploy finish.
concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          # Git dates for posts need the full history.
          # 文章的 Git 日期需要完整提交历史。
          fetch-depth: 0

      # Read the exact pnpm version from package.json's packageManager field.
      - uses: pnpm/action-setup@v6

      - name: Use Node.js LTS
        uses: actions/setup-node@v7
        with:
          node-version: lts/*

      - name: Setup Pages
        uses: actions/configure-pages@v6

      - name: Install dependencies
        # The scaffold ships package.json without a lockfile.
        run: pnpm install

      - name: Build
        run: pnpm run build

      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v5
        with:
          path: dist
          include-hidden-files: true

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v5

在使用 pnpm create valaxy 创建模版项目时，已内置文件.github/workflows/gh-pages.yml 以实现 GitHub Actions 的自动部署工作流。

• 将项目推送到 GitHub 仓库。
• 打开 Settings -> Pages，将 Pages 的源选择为 GitHub Actions。

工作流使用 Node.js LTS 和 package.json 的 packageManager 字段固定的 pnpm 版本，安装依赖并执行 pnpm run build，再通过 GitHub 官方的 Pages Actions 发布 dist 目录，包括 .well-known/ 等隐藏资源。工作流令牌只需要 contents: read、pages: write 和 id-token: write。选择源之后，如果第一次运行没有发布站点，请重新运行该工作流。

注意修改 gh-pages.yml 中的 on.push.branches 为你源代码所在的分支，默认包含 main。

Netlify ​

已内置 netlify.toml。

• 连接 GitHub 仓库，可自动部署。

Vercel ​

对于已有的 Valaxy 博客，在开始部署之前，您需要先对您博客的 vercel.json 进行修改以便启用 cleanUrls 支持：

{
  "cleanUrls": true
}

对于新创建的 Valaxy 博客，您只需要直接进行接下来的步骤即可。

• 在 Vercel 的 Dashboard 上，点击 Add New...，随后点击 Project 新建一个项目。
• 在左侧选择要部署的仓库，点击 Import，随后将 Framework Preset 设置为 Other 并更改 Build and Output Settings。
• 将 Output Directory 设置为 dist 后，点击 Deploy。
• 等待屏幕上撒下彩带后访问即可。

[build]
publish = "dist"
command = "pnpm run build"

[build.environment]
NODE_VERSION = "22"

[[redirects]]
from = "/*"
to = "/index.html"
status = 200

[[headers]]
for = "/manifest.webmanifest"

[headers.values]
Content-Type = "application/manifest+json"

Cloudflare Pages ​

• 登录你的 Cloudflare 账号，从侧边栏导航至 “Workers 和 Pages” 页面。
• 点击 创建项目、连接到 Git，选择你的 GitHub 或者 GitLab 仓库，并点击 开始设置。
• 选择你的部署分支。
• 将 构建命令 设置为 pnpm build 。
• 将 构建输出目录 设置为 dist 。
• 点击 保存并部署。

Nginx ​

Nginx Docs

下面是一个 Nginx 服务器块配置示例 nginx.conf。此配置包括对基于文本的常见资源的 gzip 压缩、使用适当缓存头为 Valaxy 站点静态文件提供服务的规则以及处理 cleanUrls: true 的方法。

server {
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;

    listen 80;
    server_name _;
    index index.html;

    location / {
        # content location
        # root /app;
        root /usr/share/nginx/html;

        # exact matches -> reverse clean urls -> folders -> not found
        try_files $uri $uri.html $uri/ =404;

        # non existent pages
        error_page 404 /404.html;

        # a folder without index.html raises 403 in this setup
        error_page 403 /404.html;

        # adjust caching headers
        # files in the assets folder have hashes filenames
        location ~* ^/assets/ {
            expires 1y;
            add_header Cache-Control "public, immutable";
        }
    }
}

本配置默认已构建的 Valaxy 站点位于服务器上的 /usr/share/nginx/html 目录中。如果站点文件位于其他位置，请相应调整 root 指令。

Docker ​

Docker Docs

下面是一个 Dockerfile 示例，用于构建 Valaxy 站点并将其部署到 Nginx 服务器中。

请参考 Nginx 部分配置 nginx.conf，并将其放置于 Dockerfile 同一目录下。

FROM node:22.12-alpine as build-stage

WORKDIR /app
RUN corepack enable

COPY .npmrc package.json pnpm-lock.yaml ./
RUN --mount=type=cache,id=pnpm-store,target=/root/.pnpm-store \
    pnpm install --frozen-lockfile

COPY . .
RUN pnpm build

FROM nginx:stable-alpine as production-stage

COPY nginx.conf /etc/nginx/nginx.conf
COPY --from=build-stage /app/dist /usr/share/nginx/html
EXPOSE 80

CMD ["nginx", "-g", "daemon off;"]

其他 ​

你还可以使用 Render 等进行托管。