---
title: "spa-loading-template.html"
description: "spa-loading-template.html 文件用于定义客户端渲染页面初始化期间显示的加载界面。"
canonical_url: "https://nuxt.zhcndoc.com/docs/4.x/directory-structure/app/spa-loading-template"
---
# spa-loading-template.html

> spa-loading-template.html 文件用于定义客户端渲染页面初始化期间显示的加载界面。

当页面以 `ssr: false` 渲染时（可以在 `nuxt.config` 中全局设置，也可以通过 [`routeRules`](https://nuxt.zhcndoc.com/docs/4.x/guide/concepts/rendering#hybrid-rendering) 为特定路由设置），服务器会返回一个不含服务端渲染应用内容的 HTML 框架。在 JavaScript bundle 下载完成、Nuxt 插件运行完毕且首个页面渲染完成之前，用户看不到页面内容。

你可以添加 `app/spa-loading-template.html` 文件来填补这段等待时间。文件内容会直接插入服务器返回的 HTML 中，因此 Nuxt 客户端 bundle 加载前就能显示。

```html [app/spa-loading-template.html]
<!-- https://github.com/barelyhuman/snips/blob/dev/pages/css-loader.md -->
<div class="loader"></div>
<style>
  .loader {
    position: fixed;
    top: 50%;
    left: 50%;
    width: 24px;
    height: 24px;
    margin: -12px 0 0 -12px;
    border: 2px solid #efefef;
    border-top-color: #000;
    border-radius: 50%;
    animation: loader 600ms linear infinite;
  }

  @keyframes loader {
    to { transform: rotate(360deg); }
  }
</style>
```

::warning
该文件是独立于 Vue 渲染的纯 HTML，因此不能在其中使用 Vue 组件或自动导入。请在此文件中直接写入加载界面所需的样式，不要依赖应用的样式表。
::

::tip
该文件只负责客户端渲染页面的首次加载。若要在页面切换时显示加载状态，请使用 [`<NuxtLoadingIndicator>`](https://nuxt.zhcndoc.com/docs/4.x/api/components/nuxt-loading-indicator) 组件。
::

## 移除时机

默认情况下，加载模板会渲染在 Nuxt 应用根元素旁边，而不是根元素内部：

```html
<div id="__nuxt"></div>
<div id="__nuxt-loader"><!-- spa-loading-template.html --></div>
```

加载界面会一直显示到首个页面准备好渲染（包括页面中的异步 setup）后再移除。这样可以避免加载界面和页面之间短暂闪白。你可以通过 [`app.spaLoaderTag`](https://nuxt.zhcndoc.com/docs/4.x/api/nuxt-config#app-spaloadertag) 和 [`app.spaLoaderAttrs`](https://nuxt.zhcndoc.com/docs/4.x/api/nuxt-config#app-spaloaderattrs) 自定义包装元素；请保留 `id`，Nuxt 会据此移除该元素。

你也可以将实验选项 [`spaLoadingTemplateLocation`](https://nuxt.zhcndoc.com/docs/4.x/guide/going-further/experimental-features#spaloadingtemplatelocation) 设为 `'within'`，让模板渲染在应用根元素内部。这种情况下，Vue 挂载应用后模板就会立即移除，因此首个页面准备好渲染之前，屏幕可能会暂时空白。

## 配置

Nuxt 会在项目及各个 [layer](https://nuxt.zhcndoc.com/docs/4.x/directory-structure/layers) 的 `app/` 目录（更准确地说，是 [`dir.app`](https://nuxt.zhcndoc.com/docs/4.x/api/nuxt-config#dir) 指定的目录）中查找 `spa-loading-template.html`。

你可以通过 [`spaLoadingTemplate`](https://nuxt.zhcndoc.com/docs/4.x/api/nuxt-config#spaloadingtemplate) 选项修改此行为：

- 使用路径指定其他 HTML 文件。路径相对于 [`srcDir`](https://nuxt.zhcndoc.com/docs/4.x/api/nuxt-config#srcdir)，默认值为 `app/`。
- 设为 `true`，在找不到文件时使用 Nuxt 内置的加载界面。
- 设为 `false`，完全禁用加载模板。

```ts twoslash [nuxt.config.ts]
export default defineNuxtConfig({
  ssr: false,
  spaLoadingTemplate: 'my-loader.html',
})
```

::read-more{to="https://nuxt.zhcndoc.com/docs/4.x/guide/concepts/rendering#client-side-rendering"}
::


## Sitemap

See the full [sitemap](https://nuxt.zhcndoc.com/sitemap.md) for all pages.