企业官网建设流程全解析

Slidev 幻灯片构建与部署完整指南：从slidev build静态站点到 GitHub Pages、Netlify、Vercel 与 Docker 托管

【免费下载链接】slidevPresentation Slides for Developers项目地址: https://gitcode.com/GitHub_Trending/sl/slidev

Slidev 的定位是"面向开发者的演示文稿"，日常编辑与演讲时它以 Web 服务器形态运行；但一场分享结束后，你往往希望把可交互的幻灯片（含 Vue 组件、绘图、点击动画等完整能力）分享给他人访问。本篇以 docs/guide/hosting.md 为骨架，结合仓库内 CLI 与构建源码，系统讲解如何把 Slidev 项目构建为可静态托管的单页应用（SPA），并给出 GitHub Pages、Netlify、Vercel、Zephyr Cloud 与 Docker 五类主流部署方案的完整可运行配置。读完本文，你将掌握slidev build全部关键参数的真实语义、构建产物的底层处理逻辑，以及一键把演讲搬到公网的方法。

为什么需要构建：从"开发服务器"到"可分享的静态站点"

Slidev 建立在 Vite 之上。在slidev（开发服务器）模式下，幻灯片通过本地 Web 服务按需编译，支持毫秒级热更新；但这也意味着页面依赖一个持续运行的 Node 进程，无法直接交给普通静态托管。

构建正是为了解决这一问题。执行构建时，Slidev 会把整份幻灯片预编译为纯静态资源（HTML + JS + CSS），任何能托管静态文件的平台（GitHub Pages、Netlify、Vercel、Nginx，甚至一个对象存储）都能承载它。从源码看，这一过程对应 packages/slidev/node/cli.ts 中注册的build [entry..]命令，其描述正是"Build hostable SPA"（构建可托管的 SPA）。

构建命令通过共享的 packages/slidev/node/commands/shared.ts 中的resolveViteConfigs合并配置：它会依次读取主题、addon 与用户根目录下的vite.config文件，最后套上 Slidev 自己的 Vite 插件，并以mode: 'production'、command: 'build'驱动底层 Vite 执行产物构建（见 packages/slidev/node/commands/build.ts）。

基础构建：slidev build与产物验证

一条命令产出可分享站点

在项目根目录执行：

$ slidev build

默认情况下，生成的静态文件被写入项目根目录下的dist文件夹。构建完成后，Slidev 会输出入口页index.html、打包后的 JS/CSS 资源以及幻灯片相关的数据文件。

要本地预览构建产物是否符合预期，官方推荐用 Vite 自带的静态预览服务：

$ npx vite preview

也可以使用任意静态文件服务器（如npx serve dist、python -m http.server等）指向dist目录。需要说明的是：vite preview只做纯静态托管，是构建后、上线前最接近真实部署环境的本地验证手段。

通过 package.json 脚本固化构建流程

如果项目是通过npm init slidev@latest（或pnpm create slidev）脚手架创建的（参见 docs/guide/index.md），package.json中已经预置了与仓库 CLI 一一对应的脚本，例如：

{ "scripts": { "dev": "slidev --open", "build": "slidev build", "export": "slidev export" } }

后续各托管平台的配置（如 Netlify 的command = 'npm run build'）均基于这一约定，因此先确认npm run build在本地可用再接入 CI/CD，可以避免大量排错。

slidev build核心参数全解

公共 Base Path：部署到子路径的关键（--base）

幻灯片中大量资源路径（JS、CSS、图片等）默认按根路径/生成。若你的站点最终挂在域名子路径下（例如https://<username>.github.io/<repository-name>/这类 GitHub Pages 项目页），必须显式指定公共基础路径：

$ slidev build --base /talks/my-cool-talk/

--base的值必须以/开头并以/结尾，缺一不可。这一约束不仅在文档层面明确要求，也被 CLI 源码强制执行——packages/slidev/node/cli.ts 中对base存在形如base.startsWith('/') && base.endsWith('/')的校验逻辑；同时--base的 CLI 帮助文本给出的示例即/demo/（见 packages/slidev/node/cli.ts）。传入的base最终会直接映射到 Vite 的build.base配置，因此也遵循 Vite 关于 public base path 的全部约定（如base: '/'、base: '/foo/'、base: './'等形态）。

自定义输出目录（--out/-o）

默认输出目录为项目根目录下的dist，可通过--out修改，并提供别名-o：

$ slidev build --out my-build-folder

从 CLI 定义看（packages/slidev/node/cli.ts），out的默认值正是'dist'，说明"默认产物在dist"这一行为来自命令行缺省值而非写死的逻辑。

剔除演讲者备注（--without-notes）

幻灯片中的备注（speaker notes）属于演讲者私密信息。若公开分享构建产物、又不希望备注被一并携带，可在构建时直接剥离：

$ slidev build --without-notes

对应 CLI 选项描述为"exclude speaker notes from the built output"（packages/slidev/node/cli.ts），在参数类型上对应BuildArgs['without-notes']（见 packages/types/src/cli.ts）。

一次构建多份幻灯片

build命令的入口参数支持多个 Markdown 文件（即 CLI 定义中的build [entry..]）。你可以显式罗列多个文件：

$ slidev build slides1.md slides2.md

如果 shell 支持 glob 通配，也可以直接匹配一批文件：

$ slidev build *.md

此时构建流程会对每个入口文件单独执行一次完整构建（见 packages/slidev/node/cli.ts 的for...of循环），并且输出目录布局有讲究：单入口时产物直接落入--out指定目录；多入口时则会在输出目录下为每个文件各自生成一个以 Markdown 文件名（去扩展名）命名的子文件夹：

// 源码片段（语义还原） build: { outDir: entry.length === 1 ? out : path.join(out, path.basename(entryFile, '.md')) }

例如slidev build a.md b.md --out public会生成public/a/与public/b/两套独立站点，非常适合在一个仓库中同时维护并发布多场演讲。

选项速查表

补充说明：--router-mode虽未在 docs/guide/hosting.md 中展开，但它是解决子路径部署路由问题的有力工具——例如在 GitHub Pages 这类"仅支持静态文件、无法自定义 SPA fallback"的场景中，hash模式能让路由完全由前端片段（/#/...）承载，避免刷新 404。

其他相关能力

--download（-d） 可在构建产物中附带一份 PDF，供访客从演示页直接下载；这与"导出 PDF"的完整教程 docs/guide/exporting.md 互补。此外，构建产物的 Open Graph 分享图可通过 SEO 元信息配置 中的seoMeta.ogImage控制，详见下文源码解读。

构建产物里发生了什么：build.ts的收尾工作

slidev build并非简单地把 Vite 产物原样吐出——packages/slidev/node/commands/build.ts 在底层 Vite 构建完成后还做了一系列面向托管的"适配"，理解这些能让部署排错事半功倍：

• 自动生成404.html（为 GitHub Pages 兜底）：构建收尾阶段会把index.html复制一份为404.html（见 packages/slidev/node/commands/build.ts）。原因在于 GitHub Pages 无法自定义 SPA fallback 规则，遇到未匹配路径时会返回自定义 404 页面；复制 index 到 404 即可让"深链接/刷新"退化为可用的 SPA 入口。这也是dist目录里会多出一个404.html的由来。
• 自动生成_redirects（服务 Netlify 等平台）：若产物目录中尚无_redirects文件，构建器会写入一行形如<base>* <base>index.html 200的 SPA 重定向规则（见 packages/slidev/node/commands/build.ts），让 Netlify 一类平台把所有路径请求回退到入口页。
• OG 分享图自动截图：当配置了seoMeta.ogImage: 'auto'（或相对路径图片）时，构建器会启动本地静态服务并驱动无头浏览器渲染第一页幻灯片，生成og-image.png并拷贝进产物（见 packages/slidev/node/commands/build.ts）。该特性说明构建阶段本身依赖 Chromium，相关环境要求可参考 docs/guide/exporting.md。
• 下载 PDF 开关：当 frontmatter/配置的download为真（或命令行传--download）时，构建末尾会额外走一遍 PDF 导出管线，把可下载文件放进产物目录（见 packages/slidev/node/commands/build.ts）。

换句话说，Slidev 的dist已经针对"被静态托管"做了相当多的内置适配，部署时通常只需再补一层入口 fallback（见下文各平台的 redirect/rewrite 规则）即可。

托管到 GitHub Pages（GitHub Actions）

官方推荐通过 GitHub Actions 在每次 push 时自动构建并发布。若项目尚无.github/workflows/deploy.yml，可按下述步骤配置：

1. 在仓库Settings→Pages中，Build and deployment来源选择GitHub Actions（不要选择Deploy from a branch手动上传dist目录，后者不利于自动化与可复现）。
2. 创建.github/workflows/deploy.yml，写入以下内容：

name: Deploy pages on: workflow_dispatch: push: branches: [main, master] permissions: contents: read pages: write id-token: write concurrency: group: pages cancel-in-progress: false jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v7 - uses: actions/setup-node@v6 with: node-version: 'lts/*' - name: Setup @antfu/ni run: npm i -g @antfu/ni - name: Install dependencies run: nci - name: Build run: nr build --base /${{github.event.repository.name}}/ - name: Setup Pages uses: actions/configure-pages@v6 with: enablement: true - uses: actions/upload-pages-artifact@v5 with: path: dist deploy: environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} needs: build runs-on: ubuntu-latest name: Deploy steps: - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v5

该工作流有几个值得注意的点：

• permissions中的pages: write与id-token: write是 GitHub Pages + Actions 部署所必需的权限声明；
• 构建命令nr build --base /${{github.event.repository.name}}/中的--base由仓库名动态生成——因为 GitHub Pages 项目页的 URL 形如https://<username>.github.io/<repository-name>/，必须让资源路径匹配子路径，这正是前文--base的用武之地；
• 依赖安装使用nci（来自 @antfu/ni，由npm i -g @antfu/ni安装），它能根据锁文件自动识别 pnpm/npm/yarn，与 Slidev 仓库自身的 pnpm workspace 工程实践一致；
• actions/configure-pages的enablement: true可自动开启 Pages，替代手动在仓库设置页操作。

3. 提交并推送后，工作流会在每次 push 到main/master分支时自动执行（也可在 Actions 页手动触发）。
4. 最终访问地址为https://<username>.github.io/<repository-name>/。由于--base已按仓库名注入、产物内又内置了404.html，页面路由与刷新均可正常工作。

托管到 Netlify

在项目根目录创建netlify.toml：

[build] publish = 'dist' command = 'npm run build' [build.environment] NODE_VERSION = '24' [[redirects]] from = '/*' to = '/index.html' status = 200

各字段含义：

• command：站点构建命令，对应脚手架预置的npm run build（即slidev build）；
• publish：发布目录，指向前文--out的默认输出dist；
• [build.environment].NODE_VERSION：指定构建环境的 Node 版本。Slidev 要求 Node.js 版本不低于 20.12.0（见 docs/guide/index.md），此处示例使用'24'的 LTS 新版本；
• [[redirects]]：SPA fallback——将一切路径请求回退到/index.html并返回200，保证幻灯片内部路由在刷新、直达链接时不会 404。

注意：若你在上一节改动过输出目录（如--out my-build-folder），请同步把publish改为对应目录名。此外，构建产物内置的_redirects已包含基础 SPA 回退，Netlify 的[[redirects]]属于在平台侧的显式补充。

然后到 Netlify 后台"New site from Git"导入该仓库即可，此后每次 push 都会自动构建发布。Slidev 官方文档站自身即托管于 Netlify，其仓库内的 docs/netlify.toml 是同一套 SPA fallback 模式的真实案例（官方站还在此基础上叠加了若干 301/302 跳转规则）。

托管到 Vercel

在项目根目录创建vercel.json：

{ "rewrites": [ { "source": "/(.*)", "destination": "/index.html" } ] }

Vercel 支持自动识别前端框架并给出合理的默认构建配置；这里的rewrites规则把任意路径重写到index.html，等价于 Netlify 场景的 SPA fallback。然后到 Vercel 后台导入仓库，确认 Build Command 为npm run build、Output Directory 为dist即可。

使用npm init slidev脚手架获得开箱即用的托管配置

上面两种平台配置并非需要从零手写——用npm init slidev@latest创建的新项目自带这些托管平台所需的配置文件。从本仓库的脚手架模板目录（packages/create-app/template）可以看到，模板中直接内置了netlify.toml、vercel.json等文件，连同.gitignore、README.md、pnpm-workspace.yaml一并初始化。因此实践中更推荐的做法是：先用脚手架生成项目，再把slides.md等内容替换为你自己的演示文稿，部署时仅需选择平台并导入仓库。

托管到 Zephyr Cloud

如果你希望使用 Zephyr Cloud（一种构建即部署的托管服务），可以在现有 Slidev 项目中通过 codemod 快速接入：

npx with-zephyr@latest

该工具会检测你当前使用的打包器（Slidev 基于 Vite）并自动更新项目配置。接入后，直接执行你平时的构建命令即可触发部署：

npm run build

当构建在启用 Zephyr 的状态下运行成功后，应用即完成部署，终端会返回一个预览 URL。

需要注意 Zephyr Cloud 与多数托管平台的一个关键差异：每一次build运行都会触发一次部署，而不像传统平台那样由"推送到指定分支"驱动。这意味着你的本地slidev build也会产生部署动作，习惯本地反复构建验证时务必留意这一行为。

用 Docker 快速托管演示

如果你偏好容器化，或需要在服务器上快速拉起一场演示，可直接使用社区维护的 Slidev Docker 镜像。

直接运行镜像

在幻灯片工作目录下执行：

docker run --name slidev --rm -it \ --user node \ -v ${PWD}:/slidev \ -p 3030:3030 \ -e NPM_MIRROR="https://registry.npmmirror.com" \ tangramor/slidev:latest

参数要点：

• -v ${PWD}:/slidev：把当前目录挂载进容器作为幻灯片工作区；
• -p 3030:3030：暴露演示服务端口（与 Slidev 开发服务器默认端口一致）；
• --user node：以非 root 的node用户运行，更符合容器安全实践；
• -e NPM_MIRROR：指定 npm 镜像源以加速依赖安装——当你的工作目录为空时，容器会生成一套模板slides.md及相关文件，并在3030端口启动服务，因此镜像源在国内网络环境下能显著缩短首次启动时间。

启动后通过http://localhost:3030/访问幻灯片。

基于镜像打包你自己的演示

先创建 Dockerfile：

FROM tangramor/slidev:latest ADD . /slidev

然后构建并运行：

docker build -t myslides . docker run --name myslides --rm --user node -p 3030:3030 myslides

访问http://localhost:3030/即可看到你自己的演示。这种方式很适合把"一场演讲"封装成独立镜像，在任意具备 Docker 的机器上一键运行。

小提示与进阶阅读

• 本地脚手架与命令入口：快速创建项目可参考 docs/guide/index.md；slidev build之外还有slidev dev、slidev export、slidev format等命令，完整清单见 docs/builtin/cli.md。
• 导出 PDF / PNG / PPTX：托管前若需同步分发离线版本，参见 docs/guide/exporting.md。
• 远程资源打包：若幻灯片中引用了远程图片等资源，部署前可阅读 docs/features/bundle-remote-assets.md，把依赖资源一并固化进构建产物，避免线上加载漂移。
• 仓库内可直接体验的样例：demo/starter 是入门模板（含页面导入、组件、外部片段等基础结构），demo/composable-vue 是较完整的交互型演讲示例（大量自定义 Vue 组件 + Monaco 编辑器集成），两者都可通过npm run build验证本篇的构建流程，再对照产物dist观察404.html、_redirects、OG 图等内置适配行为。

小结

slidev build把"开发态 Web 服务"封装为"任意静态托管可承载的 SPA"，其价值在于让演示文稿保持完整的交互能力。围绕这条主线，你可以掌握三件事：一是用--base、--out、--without-notes、多入口等参数精确控制构建产物形态；二是理解dist中404.html、_redirects、OG 图等"隐藏资产"如何在 GitHub Pages / Netlify 等平台兜底 SPA 路由；三是直接复用本文给出的 GitHub Pages Actions 工作流、netlify.toml、vercel.json、Zephyr codemod 或 Dockerfile 完成真实部署。至此，你的下一场分享将不再局限于本地演示，而可以是一个随时可访问、可交互、可被任何人打开链接观看的线上站点。

【免费下载链接】slidevPresentation Slides for Developers项目地址: https://gitcode.com/GitHub_Trending/sl/slidev