Nuxt public/ 目录详解：静态资源如何被原样托管，以及 Vite 与 Nitro 背后的处理机制

本篇技术指南围绕 Nuxt 项目中的 public/ 目录展开：它负责以根路径原样托管不参与构建处理的静态文件（如 robots.txt、favicon.ico）。读完本文，你将掌握 public/ 目录的正确使用方式、publicAssetsURL() 组合式 API 的用法，并理解 Nitro 如何注册这些静态资源、Vite 插件如何在 CSS 与 JS 中自动改写对 public 资源的引用——从配置到源码实现形成完整闭环。

一、public/ 目录的核心定位

public/ 目录中的文件直接以站点根路径提供服务，且完全不受构建流程的修改（不压缩、不重命名、不加内容 hash）。这意味着：

• 适合必须保持文件名的文件，例如 robots.txt；
• 适合基本不会变化的文件，例如 favicon.ico；
• 文件在 public/ 中如何组织，线上就如何访问：public/og-image.png 对应 URL /og-image.png。

典型目录结构如下：

-| public/
---| favicon.ico
---| og-image.png
---| robots.txt

以社交分享图为例，可以在页面中引用这些文件（例如 app/app.vue）：

<script setup lang="ts">
useSeoMeta({
  ogImage: '/og-image.png',
})
</script>

提示：在 Nuxt 2 中，这个目录被称为 static/。迁移到 Nuxt 3 时，将 static/ 整体重命名为 public/ 即可。

public/ 目录在 Nuxt 中的默认位置由 目录结构文档 定义。需要强调的是，它不是构建入口——放入其中的资源不会经过 Vite 的转译与优化管线，这一点与需要走构建管线的 assets/ 目录（SCSS、别名导入、按需打包等）形成鲜明对比。

二、源码层面：public/ 如何被注册为静态资源目录

public/ 目录之所以“原样托管”，是因为 Nuxt 在初始化 Nitro（Nuxt 的服务器引擎）时，把它显式注册进了 Nitro 的 publicAssets 列表。

在 nitro-server 模块的 bundle 逻辑 中，Nuxt 会遍历所有层（layer）的目录结构，把每个真实存在的 dirs.public 目录收集起来：

const layerPublicAssetsDirs: Array<{ dir: string, maxAge: number }> = []
for (const dirs of layerDirs) {
  if (existsSync(dirs.public)) {
    layerPublicAssetsDirs.push({ dir: dirs.public, maxAge: 0 })
  }
}

注意两个细节：

1. maxAge: 0：public 资源默认不设置浏览器缓存时长。这与构建产物形成对比——在 Nitro 的 publicAssets 配置 中，客户端构建产物（buildAssetsDir）在开发环境同样 maxAge: 0，而在生产环境则被设置为 31536000（1 年），因为产物文件名自带内容 hash，可以安全地长期缓存：

publicAssets: [
  nuxt.options.dev
    ? { dir: resolve(nuxt.options.buildDir, 'dist/client'), maxAge: 0 }
    : {
        dir: join(nuxt.options.buildDir, 'dist/client', nuxt.options.app.buildAssetsDir),
        maxAge: 31536000 /* 1 year */,
        baseURL: nuxt.options.app.buildAssetsDir,
        ignore: false,
      },
  ...layerPublicAssetsDirs,
],

2. 层（layers）天然支持：...layerPublicAssetsDirs 的展开意味着每个 Nuxt 层各自的 public/ 目录都会作为独立的 public asset 目录被注册，静态资源可以按层拆分存放。

此外，Nitro 还会注入一些框架级的 public 资源。例如在 构建 manifest 相关配置 中，Nuxt 会 unshift 注册 build meta 与 latest build 两个目录，maxAge 分别为 1 年和 1 秒，用于支持部署后的客户端缓存失效机制。

三、public 资源引用的自动改写：publicAssetsURL()

当你在代码中需要以编程方式引用 public 资源时，Nuxt 提供了自动导入的 publicAssetsURL() 组合式 API。它的实现位于 Nuxt 生成的路径模板中，见 templates.ts：

export const buildAssetsURL = (...path) => joinRelativeURL(publicAssetsURL(), buildAssetsDir(), ...path)
// ...
export const publicAssetsURL = (...path) => { /* 拼接 app.baseURL 与路径 */ }
// ...
globalThis.__publicAssetsURL = publicAssetsURL

同时，在 Nitro 配置阶段的自动导入别名 中，__publicAssetsURL 被别名为 publicAssetsURL，保证客户端与服务器两侧都能使用同一个语义化的函数名。使用示例：

const favicon = publicAssetsURL('/favicon.ico')   // 自动处理 baseURL 前缀

直接使用 /og-image.png 这类硬编码根路径在绝大多数场景也能工作，但一旦为应用设置了 app.baseURL（应用部署在子路径下），publicAssetsURL() 会自动补上前缀，避免资源 404。

四、Vite 插件：CSS 与 JS 中 public 引用的“静默”处理

一个容易被忽视但非常关键的实现细节是：即使你直接写了 url(/logo.svg) 这样的绝对路径，Nuxt 的 Vite 插件也会替你校正它。核心实现位于 public-dirs.ts。

该插件导出的 PublicDirsPlugin 返回两个 Vite 插件，分工如下：

4.1 开发环境：为 CSS url() 补上 baseURL 前缀

第一个插件 nuxt:vite-public-dir-resolution-dev 仅在 dev 模式且 baseURL 不为 / 时生效。它扫描 CSS 中的 url(/...) 模式，逐一验证该 URL 是否真实指向某个 public asset 目录中的文件，若是则将其改写为带 baseURL 前缀的完整地址（例如 url(/logo.svg) → url(/cdn/logo.svg)）。

4.2 公共逻辑：resolveId / load 的虚拟模块桥接

resolveId 钩子拦截以 / 开头的导入 id，调用 resolveFromPublicAssets(id) 判断：

function resolveFromPublicAssets (id: string) {
  for (const dir of nitro?.options.publicAssets || []) {
    if (!id.startsWith(withTrailingSlash(dir.baseURL || '/'))) { continue }
    const path = id.replace(PUBLIC_ASSETS_RE, '').replace(withTrailingSlash(dir.baseURL || '/'), withTrailingSlash(dir.dir))
    if (existsSync(path)) {
      return id
    }
  }
}

注意它遍历的正是 Nitro 的 publicAssets 列表——也就是说你在 nitro.publicAssets 中额外配置的目录同样受这套解析保护。命中后，id 被改写为带 \0 前缀的虚拟模块 \0virtual:public?<url>（resolveFromPublicAssets 位于 public-dirs.ts）。load 钩子随后将该虚拟模块的源码生成为一行对 publicAssetsURL() 的调用，从而把静态字符串转为带 baseURL 的运行时解析。renderChunk 阶段则进一步把内联样式（<style> 块）中的 url(/...) 改写为 url(" + publicAssetsURL("/logo.svg") + ") 形式，并且会根据外层字符串字面量的引号风格（单引号/双引号）保持一致。

4.3 测试用例验证的行为边界

public-dirs 测试 清晰地界定了该插件的行为契约：

• 开发环境 CSS：每个 public 资源 URL 都被加上 baseURL 前缀，且 baseURL 带尾部斜杠时不会产生双斜杠；
• generateBundle：输出 CSS 资产中的 url(/logo.svg) 被相对化为 url(../logo.svg)（相对于 CSS 文件所在目录）；
• renderChunk：chunk 中的 url(/...) 全部改写为 publicAssetsURL() 调用；不存在的资源（如 /missing.svg）保持原样不动；引号风格随字符串字面量自适应。

这套机制的价值在于：即使资源引用写在 Vite 本不该感知的 CSS 字符串里，Nuxt 也能保证 baseURL、部署路径变更时不发生资源 404。

五、配置注意事项与诊断

围绕 public/ 目录，源码中有两处值得开发者注意的配置约束：

1. 不要直接设置 vite.publicDir。schema 类型定义 明确说明：直接配置 vite.publicDir 不受支持，正确做法是设置 Nuxt 的 dir.public 选项（默认值即 public）。这保证了目录解析统一走 Nuxt 的层目录系统（getLayerDirectories），而不是 Vite 自己的逻辑。

2. 自定义 publicAssets 目录必须真实存在。Nitro 初始化时 会对每个 nitro.publicAssets 条目做存在性检查，缺失的目录会触发 NUXT_B7023 诊断（bundler 诊断类），提示你该目录不存在、其 baseURL 下的请求将直接得到硬 404。

六、实战决策：public/ 放什么、不放什么

综合上述实现，可以提炼出以下决策规则：

资源类型	建议位置	原因
robots.txt、sitemap.xml、favicon.ico	public/	必须保持文件名，且几乎不变，maxAge: 0 也符合“小文件不缓存”的直觉
og-image.png 等分享图、法律/政策静态页	public/	长期稳定，直接 URL 访问
需要编译的 CSS/SCSS、需要打包的代码依赖	assets/（配合 Vite 管线）	走构建流程可获得压缩、tree-shaking、hash 命名与 1 年缓存
只有服务端读取的文件（如 API 数据）	server/ 目录，通过 nitro.serverAssets 配置	不对外暴露，不占用 public 带宽

需要留意的限制：public/ 资源不参与内容 hash 命名，文件名一旦改变旧 URL 即失效；由于 maxAge: 0，它们也不会被浏览器长期缓存。对于频繁变更的静态内容，应优先让资源走 buildAssetsDir 管线（生产环境享受 hash 文件名 + 1 年缓存），或自行在 nitro.publicAssets 条目中为特定目录配置合理的 maxAge 与 baseURL。

小结

public/ 目录是 Nuxt 中“零构建”静态资源的出口：Nitro 将其注册为 publicAssets（默认 maxAge: 0），Vite 侧的 PublicDirsPlugin 则负责对 CSS/JS 中硬编码的 public 路径做 baseURL 感知改写与虚拟模块桥接。理解这条从 文档 到 Nitro 注册、再到 Vite 插件 的完整链路，能帮助你准确判断哪些文件属于 public/、如何安全地配置自定义静态目录，以及在部署到子路径（baseURL）场景下资源引用不会失效的原因。