框架支持

Virex 为所有主流 Web 框架提供零配置支持。当你连接仓库后，我们会自动检测你的框架并配置最佳构建设置。

支持的框架

React 生态

框架	检测依据	构建命令	输出目录
Next.js	next.config.js	next build	.next
Gatsby	gatsby-config.js	gatsby build	public
Create React App	react-scripts	react-scripts build	build
Vite (React)	vite.config.js	vite build	dist
Remix	remix.config.js	remix build	build

Vue 生态

框架	检测依据	构建命令	输出目录
Nuxt 3	nuxt.config.ts	nuxt build	.output
Vue CLI	vue.config.js	vue-cli-service build	dist
Vite (Vue)	vite.config.js	vite build	dist
VitePress	vitepress	vitepress build	.vitepress/dist

其他框架

框架	检测依据	构建命令	输出目录
Astro	astro.config.mjs	astro build	dist
SvelteKit	svelte.config.js	vite build	build
SolidStart	solid-start	solid-start build	.output
Qwik	qwik	qwik build	dist
Angular	angular.json	ng build	dist
Eleventy	.eleventy.js	eleventy	_site
Hugo	hugo.toml	hugo	public
Jekyll	_config.yml	jekyll build	_site

自动检测

部署时，Virex 会分析你的仓库并检测：

1. 包管理器 — npm、yarn、pnpm 或 bun
2. 框架 — 基于配置文件和依赖项
3. 构建命令 — 框架默认命令或来自 package.json
4. 输出目录 — 构建产物所在位置
5. Node 版本 — 来自 .nvmrc、.node-version 或 engines

首次部署时会自动执行检测：

$ virex deploy

Detecting project settings...
  Framework: Next.js 14
  Build Command: next build
  Output Directory: .next
  Node Version: 20.x

Building...

框架专属优化

Next.js

Virex 与 Next.js 深度集成：

// Automatic optimizations applied:
// - Image optimization via Virex CDN
// - ISR support with edge caching
// - Middleware runs at the edge
// - API routes deployed as serverless functions

App Router 和 Pages Router 均受完整支持。

对于 ISR（增量静态再生）：

// app/news/[slug]/page.js
export const revalidate = 3600; // Revalidate every hour

// Virex automatically:
// - Caches pages at the edge
// - Revalidates in the background
// - Serves stale content while revalidating

Astro

Astro 项目针对静态与混合渲染进行了优化：

// astro.config.mjs
export default defineConfig({
  output: 'hybrid', // or 'static', 'server'
  adapter: virexAdapter(), // Optional: use Virex adapter
});

SSR 路由会以无服务器函数形式部署，静态页面则在全球边缘节点缓存。

Remix

Remix 应用获得全栈部署支持：

// Automatic handling of:
// - Loaders and actions as serverless functions
// - Static assets on CDN
// - Streaming SSR support
// - Deferred data loading

Nuxt 3

Nuxt 3 项目利用 Nitro 实现最佳部署效果：

// nuxt.config.ts
export default defineNuxtConfig({
  nitro: {
    preset: 'virex', // Optional: explicit preset
  },
});

自定义配置

在 virex.config.js 中覆盖自动检测到的设置：

export default {
  framework: 'nextjs', // Explicit framework
  buildCommand: 'npm run build:production',
  outputDirectory: 'out',
  installCommand: 'npm ci',
  nodeVersion: '20.x',
};

也可以在控制台的「项目设置」中进行配置。

构建环境

Node.js 版本

指定你的 Node.js 版本：

// package.json
{
  "engines": {
    "node": "20.x"
  }
}

或使用版本文件：

# .nvmrc
20.11.0

支持的版本：18.x、20.x、22.x

包管理器

Virex 自动检测你的包管理器：

锁文件	包管理器
package-lock.json	npm
yarn.lock	Yarn
pnpm-lock.yaml	pnpm
bun.lockb	Bun

环境变量

框架相关的环境变量会自动设置：

# Always set
NODE_ENV=production
CI=true

# Next.js
NEXT_TELEMETRY_DISABLED=1

# Nuxt
NUXT_TELEMETRY_DISABLED=1

Monorepo 支持

Virex 支持包含多个框架的 monorepo：

my-monorepo/
├── apps/
│   ├── web/          # Next.js
│   ├── docs/         # Astro
│   └── admin/        # Remix
├── packages/
│   └── ui/           # Shared components
└── package.json

为每个项目配置根目录：

// virex.config.js (in apps/web)
export default {
  rootDirectory: 'apps/web',
};

也可以在控制台的 Settings → General → Root Directory 中设置。

静态导出

对于支持静态导出的框架：

// Next.js - next.config.js
module.exports = {
  output: 'export',
};

// Nuxt - nuxt.config.ts
export default defineNuxtConfig({
  ssr: false,
});

// Astro - astro.config.mjs
export default defineConfig({
  output: 'static',
});

静态导出的站点会部署到我们的边缘网络，并采用最优缓存策略。

故障排查

框架未被检测

请确保配置文件位于仓库根目录（或指定的根目录）中：

virex deploy --debug

构建命令失败

先在本地测试：

npm run build

检查所有依赖是否都声明在 package.json 中，而非全局安装。

输出目录错误

显式指定输出目录：

export default {
  outputDirectory: 'dist', // or 'build', 'out', etc.
};

缺少环境变量

框架构建可能需要某些环境变量。请在控制台或 .env 文件中添加：

# Required for some frameworks
NEXT_PUBLIC_API_URL=https://api.example.com