配置

在项目根目录创建 pareto.config.ts 来自定义 Pareto 的行为。

import type { ParetoConfig } from '@paretojs/core'

const config: ParetoConfig = {
  // 选项
}

export default config

ParetoConfig 类型

interface ParetoConfig {
  appDir?: string
  outDir?: string
  wkWebViewFlushHint?: boolean
}

选项

`appDir`

包含路由文件的目录。默认为 app。

`outDir`

生产构建的输出目录。默认为 .pareto。

`wkWebViewFlushHint`

在 HTML 骨架中注入一个包含 200+ 零宽字符的隐藏元素，强制 iOS WKWebView 在流完成前开始渲染。WebKit 在可见文本超过 200 个字符之前会延迟首次绘制，这可能导致在原生 iOS 应用中加载文本较少的页面时出现白屏闪烁。无视觉效果，屏幕阅读器会忽略。仅影响 WKWebView — Safari 和 Chrome 浏览器不受影响。默认为 false。

自定义 Vite 配置

Pareto 原生使用 Vite。要自定义 Vite，在项目根目录创建标准的 vite.config.ts 即可 — Pareto 在 dev 和 build 模式下都会自动加载并合并该配置。

import { defineConfig } from 'vite'
import tsconfigPaths from 'vite-tsconfig-paths'

export default defineConfig({
  plugins: [tsconfigPaths()],
  resolve: {
    alias: { '@': '/src' },
  },
  ssr: {
    noExternal: ['some-esm-only-pkg'],
    external: ['heavy-library'],
  },
})

要针对客户端或服务端构建分别配置，使用 Vite 原生的 isSsrBuild 参数：

export default defineConfig(({ isSsrBuild, command }) => ({
  plugins: [
    // 仅客户端插件
    !isSsrBuild && clientOnlyPlugin(),
  ].filter(Boolean),
}))

使用场景：

添加 Vite 插件（Tailwind、SVG 导入、tsconfig-paths 等）
配置 SSR externals（仅 Node.js 的包）
添加路径别名（resolve.alias）
修改开发服务器代理设置

完整配置项见 Vite 配置参考。

环境变量

Pareto 使用 Vite 内置的环境变量处理。以 VITE_ 为前缀的变量会暴露给客户端代码：

VITE_API_URL=https://api.example.com    # 客户端和服务端均可用
DATABASE_URL=postgres://localhost/mydb   # 仅服务端

在代码中访问：

// 客户端和服务端
const apiUrl = import.meta.env.VITE_API_URL

// 仅服务端（loader、资源路由）
const dbUrl = process.env.DATABASE_URL

Vite 支持 .env、.env.local、.env.development 和 .env.production 文件。详见 Vite 环境变量文档。

CLI 命令

pareto dev          # 启动带有 HMR 的开发服务器
pareto build        # 构建生产版本
pareto start        # 启动生产服务器

开发选项

pareto dev --port 8080    # 自定义端口（默认：3000）
pareto dev --host 0.0.0.0 # 暴露到网络

构建选项

pareto build              # 构建生产版本

生产选项

pareto start              # 启动生产服务器（默认端口：3000）
pareto start --port 8080  # 自定义端口

端口配置

默认端口为 3000。可通过以下方式更改（按优先级从高到低）：

CLI 参数：pareto dev --port 8080
环境变量：PORT=8080 pareto dev
默认值：3000

生产部署

生产部署时，先构建再启动：

npm run build    # 执行 pareto build
npm run start    # 执行 pareto start

构建输出（位于配置的 outDir 中，默认 .pareto）：

.pareto/client/ — 静态资源（JS、CSS、图片），可部署到 CDN
.pareto/server/ — 服务端包，用于 Node.js 运行时

最小化生产 Dockerfile：

FROM node:20-alpine
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN corepack enable && pnpm install --frozen-lockfile --prod
COPY .pareto/ .pareto/
EXPOSE 3000
CMD ["npx", "pareto", "start"]

配置