7.4 文档站与 Vue 项目部署
本章目标： 知道哪些文件需要发布、域名和子目录何时配置，以及文档页面和 SPA 路由的区别。本章给出可自行执行的配置，不会自动发布站点。
一眼分清产物
| 应用 | 构建位置 | 产物 | 服务方式 |
|---|---|---|---|
| Docusaurus 文档 | 当前仓库根目录 | build/ | 静态文件服务 |
| Vue 实战前端 | examples/task-board/web | dist/ | 静态文件 + SPA 路由回退 |
| ASP.NET Core API | examples/task-board/api | dotnet publish 指定目录 | .NET 进程 / IIS 托管 |
文档站展示学习内容，不运行任务 API。三个产物可以分别部署，也可以按需要安排域名与反向代理。
构建文档站
在仓库根目录运行：
$env:SITE_URL = 'https://learn.example.com'
$env:BASE_URL = '/'
npm ci
npm run typecheck
npm run build
npm run serve -- --port 3000 --no-open
访问 http://localhost:3000/，检查首页、深层文章、中文搜索和主题切换。把整个 build 目录里的内容发布到静态网站根目录，包括搜索索引和 assets。
SITE_URL 应只包含站点 origin，路径放 BASE_URL。默认域名是示例值，实际部署前设置成自己的域名，以生成正确的 canonical 和 sitemap。
子目录部署
$env:SITE_URL = 'https://example.com'
$env:BASE_URL = '/vue-study/'
npm run build
把产物映射到 /vue-study/。baseUrl 要有首尾斜杠，需要在构建前设置，不能只在服务器上换一个目录名。
预览地址也带 /vue-study/。改回根目录部署时将 BASE_URL 设回 /。当前项目未配置 GitHub 账号，发布 GitHub Pages 时可用 CI 上传静态产物，不直接使用模板默认的 deploy 配置。
文档站放到 Nginx
server {
listen 80;
server_name learn.example.com;
root /var/www/vue-study;
index index.html;
location / {
try_files $uri $uri/ =404;
}
error_page 404 /404.html;
}
当前 Docusaurus 设置 trailingSlash: true，文章生成目录形式的 index.html。正式环境另外配置 HTTPS。静态托管平台通常不需要自己写 Nginx 配置。
文档站放到 IIS
启用 IIS 的静态内容功能，将网站或应用的物理路径指向 build 内容。确认默认文档包含 index.html，并允许 .svg、.json、.woff2 等资源类型。
Docusaurus 输出静态文章，不需要安装 ASP.NET Core Hosting Bundle 来提供这些文件。Hosting Bundle 是另行托管 .NET API 时才需要的。
构建与发布 Vue 实战
npm ci
npm test
npm run build
npm run preview
把 dist 内容上传到前端网站。示例使用相对 /api，生产需将该前缀转发给 .NET；Vite 开发代理不会被发布。
如果后续加入 Vue Router 的 History 路由，Nginx 可按下面方式分开 API 和前端回退：
location /api/ {
proxy_pass http://127.0.0.1:5080;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
location / {
try_files $uri $uri/ /index.html;
}
这里 proxy_pass 没有尾部 /，保留 /api/... 路径。生产 API 根据部署配置处理受信代理的 Forwarded Headers。不要让 /api 的 404 被回退成前端 HTML。
发布 ASP.NET Core
dotnet publish -c Release -o ./publish
可部署到 IIS、Linux systemd 服务或容器，按目标系统安装对应 .NET 运行时。示例目标框架是 .NET 10，若改为其他版本，应同时检查 SDK、运行时和支持周期。
示例使用内存存储、无身份认证，仅用于学习。数据持久化、授权、HTTPS、正式错误记录和运维配置需要按实际项目补齐。完成网页构建不等于这些生产能力已经实现。
缓存与更新
带内容哈希的 assets 可以长期缓存；HTML 和搜索索引要配合更新策略，避免 HTML 引用已经删掉的旧资源。部署时保留或原子切换完整版本，比逐文件覆盖更稳妥。
验收： 从一个深层文章直接进入、刷新、执行中文搜索；Vue 项目刷新真实路由并调用 API。参考：Docusaurus 部署、Vite 静态部署。