文件系统排除规则

项目配置与基础使用 文件系统排除规则

Vite.js 允许通过配置排除特定文件或目录，避免它们被处理或包含在构建结果中。文件系统排除规则在优化构建性能、避免敏感文件泄露或跳过不必要的处理时非常有用。

配置排除规则的基本方法

在 vite.config.js 中，可以通过 server.fs.deny 或 server.fs.allow 选项控制文件系统的访问权限。这两个选项接受一个数组，可以包含字符串、正则表达式或函数。

import { defineConfig } from 'vite'

export default defineConfig({
  server: {
    fs: {
      // 禁止访问以下文件
      deny: ['.env', '.git'],
      // 只允许访问以下目录
      allow: ['src', 'public']
    }
  }
})

使用字符串模式匹配

最简单的排除方式是使用字符串路径。Vite 会将这些路径与请求的 URL 进行匹配。

export default defineConfig({
  server: {
    fs: {
      deny: [
        'node_modules',  // 排除整个 node_modules 目录
        '*.log',        // 排除所有日志文件
        'secret/*.txt' // 排除 secret 目录下的 txt 文件
      ]
    }
  }
})

使用正则表达式匹配

对于更复杂的匹配需求，可以使用正则表达式：

export default defineConfig({
  server: {
    fs: {
      deny: [
        /\.tmp$/,       // 排除所有 .tmp 文件
        /\/private\//,  // 排除包含 /private/ 路径的文件
        /^\/config\//   // 排除以 /config/ 开头的路径
      ]
    }
  }
})

使用函数进行自定义排除

当需要基于复杂逻辑进行排除时，可以使用函数：

export default defineConfig({
  server: {
    fs: {
      deny: [
        (path) => {
          // 排除大于 1MB 的文件
          const stats = fs.statSync(path)
          return stats.size > 1024 * 1024
        },
        (path) => {
          // 排除特定用户创建的文件
          const stats = fs.statSync(path)
          return stats.uid === 1000
        }
      ]
    }
  }
})

排除规则的实际应用场景

1. 保护敏感文件：防止 .env 或配置文件被意外访问
2. 提升开发服务器性能：跳过对大型二进制文件或生成文件的处理
3. 避免缓存污染：排除临时文件或日志文件
4. 安全加固：防止访问系统目录或隐藏文件

// 典型的安全配置示例
export default defineConfig({
  server: {
    fs: {
      deny: [
        '.env',
        '.env.*',
        '*.pem',
        '/etc/*',
        '/root/*',
        '/tmp/*',
        '/var/*',
        'node_modules/.cache/*'
      ],
      allow: [
        process.cwd() // 只允许访问项目根目录
      ]
    }
  }
})

排除规则与构建的关系

需要注意的是，文件系统排除规则主要影响开发服务器行为。要在生产构建中排除文件，需要使用 Rollup 的配置：

export default defineConfig({
  build: {
    rollupOptions: {
      external: [
        /^node:.*/, // 排除所有 node: 协议导入
        'fs',
        'path'
      ]
    }
  }
})

常见问题与解决方案

1. 排除规则不生效：

   • 检查路径是否正确
   • 确保没有其他配置覆盖了排除规则
   • 尝试使用绝对路径

2. 需要动态排除文件：

   export default defineConfig(({ command }) => ({
     server: {
       fs: {
         deny: command === 'serve' ? ['.env.local'] : []
       }
     }
   }))
   

3. 排除规则过于严格导致功能异常：

   • 逐步添加排除规则测试影响
   • 使用 server.fs.strict 控制严格模式

   export default defineConfig({
     server: {
       fs: {
         strict: false // 允许访问项目根目录外的文件
       }
     }
   })
   

高级排除技巧

结合多个条件进行复杂排除：

export default defineConfig({
  server: {
    fs: {
      deny: [
        (path) => {
          const isLarge = fs.statSync(path).size > 500000
          const isMedia = /\.(mp4|mov|avi)$/.test(path)
          return isLarge && isMedia
        }
      ]
    }
  }
})

使用环境变量控制排除规则：

export default defineConfig({
  server: {
    fs: {
      deny: [
        process.env.NODE_ENV === 'production' ? '.env.development' : ''
      ].filter(Boolean)
    }
  }
})

排除规则与插件系统的交互

某些插件可能会绕过 Vite 的文件系统限制。在这种情况下，需要在插件配置中单独设置：

import somePlugin from 'vite-plugin-some'

export default defineConfig({
  plugins: [
    somePlugin({
      exclude: ['**/test/**', '**/fixtures/**']
    })
  ]
})

性能考量

过度使用排除规则可能会影响构建性能，特别是在使用函数进行复杂匹配时。建议：

1. 优先使用简单的字符串或正则匹配
2. 避免在排除函数中执行同步 IO 操作
3. 对高频访问的路径使用缓存

const exclusionCache = new Map()

export default defineConfig({
  server: {
    fs: {
      deny: [
        (path) => {
          if (exclusionCache.has(path)) {
            return exclusionCache.get(path)
          }
          const result = complexCheck(path)
          exclusionCache.set(path, result)
          return result
        }
      ]
    }
  }
})

文件系统排除与模块解析

排除规则会影响模块解析行为。如果需要排除某些模块但保留它们的类型定义：

export default defineConfig({
  server: {
    fs: {
      deny: ['**/*.js'],
      allow: ['**/*.d.ts']
    }
  }
})

排除规则的调试

可以通过设置 server.debug 来查看排除规则的匹配情况：

export default defineConfig({
  server: {
    debug: {
      fs: {
        showExcluded: true
      }
    }
  }
})

这会在控制台输出被排除的文件访问尝试，帮助调试配置问题。