许多服务都可以部署静态 SPA。本页介绍通用部署要求，并给出几个常见服务商的示例。
如果缺少您常用的部署工具，欢迎在 GitHub 上创建一个 Pull Request 将其添加到列表中。
通用部署
第一步是构建生产环境包：
要生成构建产物，请使用 Quasar CLI 和以下命令：
quasar build默认情况下，构建产物输出到 /dist/spa 目录。如果您配置了 build.distDir，则部署该目录即可。
通过 HTTP 或 HTTPS 提供这些文件的访问服务。直接用 file:// 协议打开 index.html 是不支持的。
常用的 web 服务器有 nginx、Caddy、Apache、Express 等，但您可以选择任何您想要的 web 服务器。
Hash 模式路由只需要静态文件托管即可。History 模式路由还需要配置一个回退规则：当请求的应用路由没有匹配到静态文件时，将请求转发到 index.html。注意不要重写对已有静态资源的请求。
一个 nginx 的示例配置如下：
server {
listen 80;
server_name quasar.myapp.com;
root /home/user/quasar.myapp.com/public;
add_header X-Frame-Options "SAMEORIGIN";
add_header X-Content-Type-Options "nosniff";
index index.html;
charset utf-8;
location / {
try_files $uri $uri/ /index.html;
}
location = /robots.txt { access_log off; log_not_found off; }
access_log off;
error_log /var/log/nginx/quasar.myapp.com-error.log error;
location ~ /\.(?!well-known).* {
deny all;
}
}重要的部署配置
不要让浏览器长时间缓存 index.html。否则，回访用户可能会继续加载旧版本部署中的资源 URL。经过哈希处理的 JavaScript、CSS 及其他不可变资源可以设置更长的缓存时间。
通过您的托管服务为 index.html 配置重新验证策略，例如 Cache-Control: no-cache。
例如，使用 Google Firebase 部署时，需要在 firebase.json 中添加如下配置：
{
"hosting": {
"headers": [
{
"source": "/index.html",
"headers": [
{
"key": "Cache-Control",
"value": "no-cache"
}
]
},
{
"source": "**/*.@(jpg|jpeg|gif|png|svg|webp|js|css|eot|otf|ttf|ttc|woff|woff2|font.css)",
"headers": [
{
"key": "Cache-Control",
"value": "public, max-age=31536000, immutable"
}
]
}
]
}
}使用 Cloudflare Pages 部署
Cloudflare Pages 可以直接从 Git 仓库部署 SPA。配置 Pages 项目时设置：
- 构建命令：
quasar build - 构建输出目录：
dist/spa
当您推送到关联的生产或预览分支时，Cloudflare 会自动重新构建站点。如果没有部署顶层的 404.html，Pages 会将项目视为 SPA，并将未知路径路由到 index.html。
如果需要直接上传而非通过 Git 集成，可以安装 Wrangler 并部署构建目录：
pnpm add -D wrangler
pnpm quasar build
pnpm wrangler pages deploy dist/spa如果更改了 build.distDir，请传入对应的输出目录。更多信息参见 Cloudflare Pages 文档，包括 Git 集成、直接上传、重定向和自定义域名。
使用 Vercel 部署
将 Git 仓库连接到 Vercel，然后配置：
- 构建命令：
quasar build - 输出目录：
dist/spa
如果需要通过 CLI 部署，安装 Vercel CLI，登录后在项目根目录运行即可：
vercel login
vercel对于 history 模式路由，在项目根目录添加 vercel.json。文件系统检查可以让静态资源在 SPA 回退之前正常解析：
{
"rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
}您也可以定义项目脚本：
"scripts": {
"build": "quasar build",
"deploy": "vercel --prod"
}如果更改了 build.distDir，需要同步更新 Vercel 的输出目录配置。
使用 Heroku 部署
Heroku 不直接提供静态站点服务，因此应用需要一个小型 HTTP 服务器。
在本例中，我们将使用 Express 创建 Heroku 可以使用的最小服务器。
首先，为项目安装所需的依赖：
pnpm add express serve-static connect-history-api-fallback安装完成后，就可以添加服务器了。在项目根目录中创建一个名为 server.js 的文件：
import path from 'node:path'
import express from 'express'
import serveStatic from 'serve-static'
import history from 'connect-history-api-fallback'
const port = process.env.PORT || 5000
const app = express()
app.use(history())
app.use(serveStatic(path.join(import.meta.dirname, 'dist/spa')))
app.listen(port)Heroku 需要一组 package 脚本，在 package.json 的 scripts 中添加以下内容：
"scripts": {
"build": "quasar build",
"start": "node server.js",
"heroku-postbuild": "quasar build"
}现在可以在 Heroku 上通过以下命令创建应用：
heroku create然后部署到 Heroku：
git init
heroku git:remote -a <heroku app name>
git add .
git commit -am "make it better"
git push heroku main对于已有的 Git 仓库，只需添加 heroku 远程即可：
heroku git:remote -a <heroku app name>使用 Surge 部署
Surge 是托管和部署静态站点的流行工具。
如果要使用 Surge 部署应用程序，首先需要安装 Surge CLI 工具：
pnpm add --global surge接下来，使用 Quasar CLI 构建应用程序：
quasar build然后通过以下命令使用 Surge 部署应用程序：
surge dist/spa现在，您的应用已经通过 Surge 成功部署了。您可以将本指南的方法适配到任何其他静态站点部署工具。
使用 GitHub Pages 部署
GitHub Pages 可以通过 GitHub Actions 部署生产构建产物。在仓库设置中，选择 Pages > Build and deployment > GitHub Actions，然后添加 .github/workflows/deploy.yml：
name: Deploy Quasar SPA to GitHub Pages
on:
push:
branches: [main]
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: pages
cancel-in-progress: true
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v6
with:
node-version: 24
cache: pnpm
- run: pnpm install --frozen-lockfile
- run: pnpm quasar build
- uses: actions/upload-pages-artifact@v4
with:
path: dist/spa
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
needs: build
steps:
- name: Deploy
id: deployment
uses: actions/deploy-pages@v4如果是项目站点（URL 为 https://<username>.github.io/<repository>/），需要将 build.publicPath 设置为 /<repository>/。以 <username>.github.io 命名的用户或组织站点从 / 提供服务，不需要此设置。
GitHub Pages 没有提供通用的 history 模式回退到 index.html 的机制。请使用 Vue Router 的 hash 模式，除非每个路由都有对应的静态文件，或者有其他层来处理重写。
要使用自定义域名，请在仓库的 Pages 设置中进行配置。有关 DNS 和域名验证的说明，参见 GitHub Pages 文档。