初次部署Astro博客

博客系统

最近从朋友那里复制了一份 Astro 博客项目。完成站点名称、域名和文章等初始化配置后，我准备先在本地运行开发服务，再通过 Nginx 反向代理到自己的域名。这篇文章记录完整的部署过程，以及实际遇到的几个问题。

一、检查项目配置

这个项目的主要配置集中在 src/config/site.yaml。本次使用的关键配置如下：

url: https://blog.human-agent.top
basePath: ""


server:
  host: 0.0.0.0
  astroPort: 8686
  healthHost: 127.0.0.1
  allowedHosts:
    - blog.human-agent.top

其中：

  • url 是反向代理后对外访问的正式地址。
  • basePath 为空，表示博客部署在域名根路径。
  • host: 0.0.0.0 允许开发服务接受来自本机之外的连接。
  • astroPort: 8686 是 Astro 开发服务监听的端口。
  • allowedHosts 必须包含反向代理使用的域名，否则 Vite 可能拒绝请求。

复制别人的项目后，还应检查 name、作者、备案信息、统计代码、IndexNow key 和 deploy 配置。尤其不要直接使用原项目中的服务器地址、SSH 私钥路径或搜索引擎密钥。

二、安装 PowerShell 7

系统最初使用的是 Windows PowerShell 5.1。为了获得更好的Codex兼容性和后续更新，通过 winget 安装 PowerShell 7：

Terminal window
winget install --id Microsoft.PowerShell `
  --source winget `
  --exact `
  --accept-source-agreements `
  --accept-package-agreements

安装完成后重新打开终端，并检查版本：

Terminal window
$PSVersionTable

本次安装后的版本是 PowerShell 7.6.3，PSEdition 为 Core。Windows PowerShell 5.1 会继续保留，两者可以并存。

三、安装 Node.js 和配置 npm 镜像

Astro 依赖 Node.js。使用 winget 安装 Node.js LTS：

Terminal window
winget install --id OpenJS.NodeJS.LTS `
  --source winget `
  --exact `
  --accept-source-agreements `
  --accept-package-agreements

安装后重新打开终端，检查版本：

Terminal window
node --version
npm --version

本次安装的是 Node.js 24.18.0 LTS 和 npm 11.16.0。

为了提高国内网络环境下的依赖下载速度，将 npm 用户级镜像设置为 npmmirror：

Terminal window
npm config set registry https://registry.npmmirror.com --location=user
npm config get registry

配置会写入用户目录下的 .npmrc：

registry=https://registry.npmmirror.com

四、安装项目依赖

进入项目目录后，按照 package-lock.json 安装锁定版本的依赖：

Terminal window
cd D:\hwj-blog
npm ci

对于已有 lock 文件的项目，npm ci 比 npm install 更适合首次部署，因为它不会自行改写依赖版本。

本次使用 npm 11 安装时，出现了 esbuild 和 sharp 的安装脚本未被允许的提示。这两个包分别用于前端构建和图片处理，是 Astro 项目的明确依赖，可以批准并重建：

Terminal window
npm approve-scripts esbuild sharp
npm rebuild esbuild sharp

第三方项目中不要无条件执行 npm approve-scripts --all，应先确认具体包及其用途。

五、启动 Astro 开发服务

项目封装了后台服务管理脚本，可以直接启动：

Terminal window
npm run server:start

查看状态：

Terminal window
npm run server:status

常用管理命令如下：

Terminal window
npm run server:restart
npm run server:stop

服务启动后，本机访问地址为：

http://127.0.0.1:8686/

运行日志保存在项目的 .tmp/logs/ 目录。如果进程显示为运行中，但浏览器无法访问，应优先查看：

.tmp/logs/astro.out.log
.tmp/logs/astro.err.log

六、处理文章 cid 缺失

第一次启动时，Astro 内容校验报告一篇文章的 cid 是空值：

Expected type "string" | "number", received "null"

这个项目使用 cid 作为公开文章的稳定 URL ID。可以先检查所有公开文章：

Terminal window
npm run cid:check

确认只是缺失值、没有重复或非法 ID 后，使用项目脚本自动补齐：

Terminal window
npm run cid:fix

草稿目录中的文章不需要填写 cid。文章移入 archives 准备发布后，再执行检查或修复即可，==可以手动填写cid==。

七、配置 Nginx 反向代理

我主要使用宝塔面板结合Zerotier构建反代，下方内容仅作参考。

当 Nginx 和 Astro 位于同一台机器时，可以把域名反向代理到本机的 8686 端口：

location / {
    proxy_pass http://127.0.0.1:8686;
    proxy_http_version 1.1;


    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;


    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

Upgrade 和 Connection 请求头用于支持 Astro/Vite 的热更新 WebSocket。配置完成后，还需要为域名启用 HTTPS，并确认 blog.human-agent.top 已包含在 allowedHosts 中。

如果 Nginx 位于另一台服务器，127.0.0.1 不能指向开发电脑，需要改成两台机器之间实际可达的地址。更稳妥的做法是通过 WireGuard、Tailscale 或 SSH 隧道连接，而不是直接把开发端口暴露到公网。

八、最终验证

项目中已提供了dev server 相关的 start, stop, restart 的 bat 脚本，目前主要是用 dev server 热更新运行，而不是build成静态网站。

完成上述处理后，重新启动服务：

Terminal window
npm run server:start

首页最终返回 HTTP 200，Astro 完成内容同步并进入文件监听状态：

astro v5.18.2 ready
watching for file changes...

至此，本地开发环境和反向代理所需配置已经完成。需要注意的是，Astro dev server 更适合临时预览和调试。正式长期运行时，建议执行 npm run build 生成 dist/，再由 Nginx 直接托管静态文件，这样性能和稳定性都会更好。