Slidev 幻灯片构建与部署完整指南从slidev build静态站点到 GitHub Pages、Netlify、Vercel 与 Docker 托管【免费下载链接】slidevPresentation Slides for Developers项目地址: https://gitcode.com/GitHub_Trending/sl/slidevSlidev 的定位是面向开发者的演示文稿日常编辑与演讲时它以 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 slidevlatest或pnpm create slidev脚手架创建的参见 docs/guide/index.mdpackage.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.tsout的默认值正是dist说明默认产物在dist这一行为来自命令行缺省值而非写死的逻辑。剔除演讲者备注--without-notes幻灯片中的备注speaker notes属于演讲者私密信息。若公开分享构建产物、又不希望备注被一并携带可在构建时直接剥离$ slidev build --without-notes对应 CLI 选项描述为exclude speaker notes from the built outputpackages/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/两套独立站点非常适合在一个仓库中同时维护并发布多场演讲。选项速查表参数别名默认值作用仓库依据--out dir-odist指定构建产物输出目录packages/slidev/node/cli.ts--base path—无按根路径设置公共基础路径必须/开头且结尾packages/slidev/node/cli.ts--download-d—构建时同步导出 PDF允许访客一键下载同上download选项--without-notes——从产物中剔除演讲者备注packages/slidev/node/cli.ts--router-mode mode—沿用配置覆盖产物路由模式hash适合 GitHub Pages 等子目录部署memory保持 URL 无页码适合 kiosk/跟随端packages/slidev/node/cli.ts--inspect—false开启 Vite inspect 插件以便调试packages/slidev/node/cli.ts[entry..]—slides.md一个或多个 Markdown 入口多入口时为每个文件生成独立子目录packages/slidev/node/cli.ts补充说明--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* baseindex.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 PagesGitHub Actions官方推荐通过 GitHub Actions 在每次 push 时自动构建并发布。若项目尚无.github/workflows/deploy.yml可按下述步骤配置在仓库Settings→Pages中Build and deployment来源选择GitHub Actions不要选择Deploy from a branch手动上传dist目录后者不利于自动化与可复现。创建.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/checkoutv7 - uses: actions/setup-nodev6 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-pagesv6 with: enablement: true - uses: actions/upload-pages-artifactv5 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-pagesv5该工作流有几个值得注意的点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替代手动在仓库设置页操作。提交并推送后工作流会在每次 push 到main/master分支时自动执行也可在 Actions 页手动触发。最终访问地址为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 buildpublish发布目录指向前文--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 slidevlatest创建的新项目自带这些托管平台所需的配置文件。从本仓库的脚手架模板目录packages/create-app/template可以看到模板中直接内置了netlify.toml、vercel.json等文件连同.gitignore、README.md、pnpm-workspace.yaml一并初始化。因此实践中更推荐的做法是先用脚手架生成项目再把slides.md等内容替换为你自己的演示文稿部署时仅需选择平台并导入仓库。托管到 Zephyr Cloud如果你希望使用 Zephyr Cloud一种构建即部署的托管服务可以在现有 Slidev 项目中通过 codemod 快速接入npx with-zephyrlatest该工具会检测你当前使用的打包器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_MIRRORhttps://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/访问幻灯片。基于镜像打包你自己的演示先创建 DockerfileFROM 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.mdslidev 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Slidev 幻灯片构建与部署完整指南：从 `slidev build` 静态站点到 GitHub Pages、Netlify、Vercel 与 Docker 托管
Slidev 幻灯片构建与部署完整指南从slidev build静态站点到 GitHub Pages、Netlify、Vercel 与 Docker 托管【免费下载链接】slidevPresentation Slides for Developers项目地址: https://gitcode.com/GitHub_Trending/sl/slidevSlidev 的定位是面向开发者的演示文稿日常编辑与演讲时它以 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 slidevlatest或pnpm create slidev脚手架创建的参见 docs/guide/index.mdpackage.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.tsout的默认值正是dist说明默认产物在dist这一行为来自命令行缺省值而非写死的逻辑。剔除演讲者备注--without-notes幻灯片中的备注speaker notes属于演讲者私密信息。若公开分享构建产物、又不希望备注被一并携带可在构建时直接剥离$ slidev build --without-notes对应 CLI 选项描述为exclude speaker notes from the built outputpackages/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/两套独立站点非常适合在一个仓库中同时维护并发布多场演讲。选项速查表参数别名默认值作用仓库依据--out dir-odist指定构建产物输出目录packages/slidev/node/cli.ts--base path—无按根路径设置公共基础路径必须/开头且结尾packages/slidev/node/cli.ts--download-d—构建时同步导出 PDF允许访客一键下载同上download选项--without-notes——从产物中剔除演讲者备注packages/slidev/node/cli.ts--router-mode mode—沿用配置覆盖产物路由模式hash适合 GitHub Pages 等子目录部署memory保持 URL 无页码适合 kiosk/跟随端packages/slidev/node/cli.ts--inspect—false开启 Vite inspect 插件以便调试packages/slidev/node/cli.ts[entry..]—slides.md一个或多个 Markdown 入口多入口时为每个文件生成独立子目录packages/slidev/node/cli.ts补充说明--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* baseindex.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 PagesGitHub Actions官方推荐通过 GitHub Actions 在每次 push 时自动构建并发布。若项目尚无.github/workflows/deploy.yml可按下述步骤配置在仓库Settings→Pages中Build and deployment来源选择GitHub Actions不要选择Deploy from a branch手动上传dist目录后者不利于自动化与可复现。创建.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/checkoutv7 - uses: actions/setup-nodev6 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-pagesv6 with: enablement: true - uses: actions/upload-pages-artifactv5 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-pagesv5该工作流有几个值得注意的点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替代手动在仓库设置页操作。提交并推送后工作流会在每次 push 到main/master分支时自动执行也可在 Actions 页手动触发。最终访问地址为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 buildpublish发布目录指向前文--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 slidevlatest创建的新项目自带这些托管平台所需的配置文件。从本仓库的脚手架模板目录packages/create-app/template可以看到模板中直接内置了netlify.toml、vercel.json等文件连同.gitignore、README.md、pnpm-workspace.yaml一并初始化。因此实践中更推荐的做法是先用脚手架生成项目再把slides.md等内容替换为你自己的演示文稿部署时仅需选择平台并导入仓库。托管到 Zephyr Cloud如果你希望使用 Zephyr Cloud一种构建即部署的托管服务可以在现有 Slidev 项目中通过 codemod 快速接入npx with-zephyrlatest该工具会检测你当前使用的打包器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_MIRRORhttps://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/访问幻灯片。基于镜像打包你自己的演示先创建 DockerfileFROM 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.mdslidev 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考