深入理解unjs/nitro项目配置指南

深入理解unjs/nitro项目配置指南

nitro Create, build and deploy universal web servers. The open engine powering Nuxt and open to everyone. 项目地址: https://gitcode.com/gh_mirrors/ni/nitro

前言

unjs/nitro是一个现代化的JavaScript服务器框架，它提供了强大的配置选项来满足各种开发需求。本文将全面解析nitro的配置系统，帮助开发者更好地理解和运用这个框架。

基础配置

预设模式(preset)

nitro通过预设模式来适应不同的部署环境。开发模式下固定使用nitro_dev预设，生产环境默认为node_server预设。你可以通过preset选项或NITRO_PRESET环境变量来指定自定义的生产预设。

日志级别(logLevel)

日志级别默认为3(普通模式)或1(测试环境)，开发者可以根据需要调整日志详细程度。

运行时配置(runtimeConfig)

runtimeConfig用于定义服务器运行时配置，其中nitro命名空间被保留用于框架内部使用。

功能特性配置

实验性功能(experimental)

nitro提供了一系列实验性功能，可以通过experimental选项启用：

1. OpenAPI支持：启用后，系统会提供/_scalar、/_swagger和/_openapi.json端点
2. WASM支持：启用WebAssembly功能
3. 传统外部依赖处理：使用旧的rollup外部依赖算法

未来功能(future)

future选项用于配置即将在主要版本中发布的新功能，例如nativeSWR可以在Netlify和Vercel预设中使用内置的SWR功能。

静态资源处理

静态资源服务(serveStatic)

控制是否在生产环境中提供public/目录下的静态资源。建议使用边缘CDN(如Nginx、Apache)来服务.output/public/目录以获得更好的性能。

公共资源(publicAssets)

可以配置多个公共资源目录，并设置缓存控制头信息：

publicAssets: [
  {
    baseURL: "images",
    dir: "public/images",
    maxAge: 60 * 60 * 24 * 7, // 7天缓存
  },
]

资源压缩(compressPublicAssets)

支持gzip和brotli压缩，可以显著减少资源传输大小。nitro会为大于1024字节的特定MIME类型资源生成预压缩版本。

路由配置

基础URL(baseURL)

设置服务器的基础URL，默认为/，也可以通过NITRO_APP_BASE_URL环境变量指定。

API基础路径(apiBaseURL)

修改API路由的前缀，默认为/api。

路由规则(routeRules)

这是一个实验性功能，允许为特定路由模式设置规则：

routeRules: {
  '/blog/**': { swr: true }, // 启用SWR缓存
  '/assets/**': { headers: { 'cache-control': 's-maxage=0' } }, // 设置缓存头
  '/api/v1/**': { cors: true }, // 启用CORS
  '/old-page': { redirect: '/new-page' }, // 重定向
}

预渲染(prerender)

预渲染配置允许在构建时将特定路由生成为静态文件：

prerender: {
  crawlLinks: true, // 自动爬取链接
  failOnError: true, // 出错时停止构建
  routes: ['/about'], // 指定要预渲染的路由
  retry: 5, // 重试次数
}

目录结构配置

工作区目录(workspaceDir)

项目工作区根目录，通常会自动检测。

源码目录(srcDir)

项目源码目录，默认为根目录，包含api、routes、plugins等子目录。

构建目录(buildDir)

nitro生成构建相关文件的临时工作目录，默认为.nitro。

输出目录(output)

生产构建的输出目录结构：

{
  dir: '.output', // 总输出目录
  serverDir: '.output/server', // 服务器文件
  publicDir: '.output/public' // 公共资源
}

高级配置

Rollup配置

nitro使用Rollup进行打包，可以自定义Rollup配置：

• rollupConfig: 额外的Rollup配置
• minify: 是否压缩打包文件
• sourceMap: 是否生成源映射
• analyze: 启用构建分析

开发服务器(devServer)

开发服务器选项，可以通过watch配置监控文件变化。

插件系统(plugins)

nitro支持插件系统，可以按顺序执行插件。框架会自动注册plugins/目录中的插件。

总结

unjs/nitro提供了丰富而灵活的配置选项，从基础设置到高级功能，能够满足各种服务器开发需求。通过合理配置，开发者可以优化性能、简化部署流程，并充分利用框架提供的各种特性。

理解这些配置选项是掌握nitro框架的关键，建议开发者根据项目需求逐步尝试不同的配置组合，找到最适合自己项目的配置方案。

nitro Create, build and deploy universal web servers. The open engine powering Nuxt and open to everyone. 项目地址: https://gitcode.com/gh_mirrors/ni/nitro