私有部署（Debian + 宝塔面板 + Nginx）

这篇文档面向自有服务器部署场景：服务器系统为 Debian 系 Linux，使用宝塔面板管理站点，并由 Nginx 提供静态文件服务。

ShokaX 是纯静态站点（SSG）：部署的核心就是把构建产物 dist/ 放到服务器上，然后让 Nginx 指向该目录。

你会得到什么

• 一个可访问的博客域名（例如 https://blog.example.com/）
• 文章、归档、分类等页面正常打开
• 搜索（Pagefind）可用（前提：构建时生成索引）
• 静态资源缓存策略正确（/_astro/ 长缓存）

前置条件

服务器侧

• Debian 10/11/12（或同系发行版）
• 已安装宝塔面板（BT）并启用 Nginx
• 已准备好域名并解析到服务器 IP

本地侧（推荐）

推荐在本地完成构建，再上传 dist/ 到服务器（更稳定、也更快）。

• Bun 已安装
• 本地能运行 bun run build 成功

提示

如果你更习惯在服务器上构建，也可以（本文后面有“在服务器构建”的可选方案）。

第 1 种方式（推荐）：本地构建 + 上传 dist

步骤 1：配置站点 URL（重要）

请确保 astro.config.mjs 的 site 是你的线上域名（否则 sitemap / RSS / 永久链接等可能不正确）：

astro.config.mjs

export default defineConfig({
  site: "https://blog.example.com",
  // ...
});

说明：本主题启用了 trailingSlash: "always"，最终链接通常会以 / 结尾。

步骤 2：本地构建

在项目根目录执行构建：

bun install
bun run build

构建完成后会得到 dist/ 目录。

关于搜索

本主题的 bun run build 会在 astro build 后执行 pagefind --site ./dist 生成索引。

因此只要你是用 bun run build 构建，上传 dist/ 后搜索也会自动可用。

步骤 3：在宝塔创建站点

1. 进入宝塔面板 → 网站 → 添加站点
2. 填写你的域名（例如 blog.example.com）
3. Web 服务器选择 Nginx
4. 创建完成后，打开该站点的设置

TODO：补充宝塔“添加站点”界面截图

步骤 4：上传 dist 到站点目录

在宝塔站点设置里找到站点根目录（通常类似：/www/wwwroot/blog.example.com/），将本地 dist/ 目录内的全部文件上传到该目录。

上传后的目录结构应类似：

/www/wwwroot/blog.example.com/
  index.html
  pagefind/
  _astro/
  posts/
  categories/
  ...

警告

不要把 dist 文件夹本身上传成 /www/wwwroot/blog.example.com/dist/。

正确做法是：让 index.html 直接位于站点根目录。

步骤 5：配置 Nginx（伪静态 / try_files）

在宝塔面板里：站点 → 设置 → 伪静态（或“配置文件”），为 Astro 静态站点添加基础规则：

location / {
  try_files $uri $uri/ =404;
}

这条规则会让 Nginx：

• 优先寻找实际文件（例如 /favicon.svg）
• 如果是目录（例如 /posts/hello-world/），会自动读取目录下的 index.html

是否需要强制补 /

主题内部生成的链接已经遵循 trailingSlash: "always"，通常不需要额外做“自动补 /”的重定向。

如果你仍希望把 /posts/xxx 重定向到 /posts/xxx/，请谨慎编写规则，避免影响带扩展名的静态文件。 TODO：补充一个更安全的“仅对无扩展名路径补 /”的示例（如确有需求）。

步骤 6：配置 HTTPS

在宝塔面板：站点 → SSL：

1. 申请证书（Let’s Encrypt 或上传已有证书）
2. 开启 HTTPS
3. 建议开启“强制 HTTPS”

TODO：补充宝塔 SSL 配置界面截图

推荐的缓存与安全响应头（可选，但建议）

ShokaX 的静态资源位于 /_astro/，文件名通常包含 hash，适合长期缓存。

你可以在 Nginx 配置中添加：

# 1) /_astro 静态资源长期缓存
location ^~ /_astro/ {
  add_header Cache-Control "public, max-age=31536000, immutable";
  try_files $uri =404;
}

# 2) 全站基础安全响应头
add_header Content-Security-Policy "frame-ancestors 'none';" always;
add_header X-Frame-Options "DENY" always;

# 如果你确认站点永远使用 HTTPS，可启用 HSTS
# add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;

注意

如果你需要把站点嵌入到其他页面（iframe），需要调整 Content-Security-Policy 的 frame-ancestors，并移除/调整 X-Frame-Options。

第 2 种方式（可选）：在服务器上构建

适用于你不方便在本地构建、希望“服务器拉代码→构建→发布”的流程。

思路

1. 服务器上安装 Bun / Git
2. 拉取仓库
3. 运行 bun install && bun run build
4. 将 dist/ 发布到站点目录（或直接让站点根目录指向仓库的 dist/）

TODO：补充“Debian 安装 Bun”的可靠步骤与参考链接（以官方文档为准）。

警告

如果你直接把站点根目录指向仓库内的 dist/，注意：每次构建都会覆盖该目录。请避免把上传的其他文件（例如验证文件）放在同一目录里。

更新站点（发布新文章/改配置）

方式 A：本地构建后上传（推荐）

1. 本地修改内容
2. bun run build
3. 上传新的 dist/ 覆盖服务器站点目录

方式 B：服务器构建

1. 服务器 git pull
2. bun install（依赖有变化时）
3. bun run build
4. 若站点根目录不是 dist/，将新的 dist/ 同步到站点目录

TODO：补充一个“用宝塔计划任务定时拉取并构建”的示例（可选）。

常见问题

Q1：部署后页面 404 / 样式丢失？

请依次检查：

1. 站点根目录是否直接包含 index.html（而不是多了一层 dist/）
2. Nginx 是否配置了 try_files $uri $uri/ =404;
3. 构建是否成功（本地或服务器 bun run build 是否无报错）

Q2：搜索不可用？

通常原因是：没有生成 Pagefind 索引或未上传 pagefind/ 目录。

检查：

• 你是否执行的是 bun run build（而不是只执行 astro build）
• 站点根目录是否存在 pagefind/

Q3：HTTPS 开启后出现混合内容（Mixed Content）？

确保：

• astro.config.mjs 的 site 是 https://...
• 第三方资源（图片/脚本）也尽量使用 HTTPS

Q4：缓存导致更新不生效？

• /_astro/ 资源通常带 hash，长期缓存不会影响更新
• 如果你更换了同名文件（例如 /favicon.svg），可能需要清理浏览器缓存或 CDN 缓存

TODO：补充宝塔/Nginx 清理缓存的常用方式（如涉及 CDN）。

相关资源

• Astro 部署指南（通用）：https://docs.astro.build/en/guides/deploy/
• 宝塔面板官方文档：TODO