部署与发布

技术栈

云图札记跑在以下几样东西上：

组件	选型	版本
框架	Astro	6.4.4
适配器	@astrojs/cloudflare	SSR 模式
Markdown	@astrojs/mdx	MDX 支持
站点地图	@astrojs/sitemap	自动生成
图像处理	Sharp	缩略图生成
代码高亮	Expressive Code	gruvbox-dark-soft
字体	Instrument Sans + JetBrains Mono	Google Fonts
部署	Cloudflare Pages	自动 CI-CD

---

服务器环境

项目跑在腾讯云轻量服务器上：

• 系统：Linux（宝塔面板）
• 项目路径：/www/wwwroot/code/yblog
• Node.js：v22.12.0（宝塔自带）
• 包管理器：pnpm（通过 Corepack）

环境注意事项

1. pnpm 路径问题：宝塔安装 pnpm 没加到全局 PATH，完整路径是：

   /www/server/nodejs/v22.12.0/lib/node_modules/corepack/shims/pnpm

如果 pnpm run build 遇到 Corepack 签名验证错误，直接用 Node 调用：

node ./node_modules/.bin/astro build

2. Google Fonts CDN：国内服务器可能访问不到 fonts.googleapis.com，所以 CSS 中必须对每个关键元素显式声明 font-family 回退链，不能只靠远程字体加载。

3. 构建产物：Astro 默认输出到 dist/ 目录，Cloudflare 适配器产物在 dist/ 下包含 _worker.js。

---

日常命令

启动开发服务器

cd /www/wwwroot/code/yblog
node ./node_modules/.bin/astro dev --port 4321 --host 0.0.0.0

• --host 0.0.0.0 允许外部 IP 访问（用于远程预览）
• 开发服务器支持热更新，修改文件后页面自动刷新

构建生产版本

cd /www/wwwroot/code/yblog
node ./node_modules/.bin/astro build

正常构建输出：

[build] 27 page(s) built in 2.87s
[build] Complete!

本地预览构建产物

node ./node_modules/.bin/astro preview --port 4321 --host 0.0.0.0

⚠️ 预览服务用完必须关闭 4321 端口，不要长期占用。

关闭端口

lsof -ti:4321 | xargs kill -9

---

Cloudflare Pages 部署

DNS 配置

域名 blog.lzplus.top 的 DNS 指向 Cloudflare，通过 Cloudflare Pages 提供托管：

1. 在 Cloudflare Pages 创建项目，关联 GitHub 仓库
2. 设置构建命令：node ./node_modules/.bin/astro build
3. 输出目录：dist/
4. 环境变量：NODE_VERSION=22

自动部署流程

本地修改 → git push → GitHub → Cloudflare Pages 自动构建 → 线上更新

每次 push 到主分支，Cloudflare 会自动拉取代码并构建部署，通常 1-2 分钟完成。

手动部署

如果不想走 CI-CD，也可以用 Wrangler CLI 手动部署：

npm install -g wrangler
wrangler pages deploy dist --project-name=yblog

注意：Cloudflare 适配器生成 _worker.js 中可能包含 Wrangler 不兼容字段，如需手动部署需先清洗。

---

Wrangler 配置清洗

如果构建后需要手动 wrangler deploy，要清洗 dist/_worker.js 中的不兼容字段：

# fix_wrangler.py
import json, re

with open('dist/_worker.js', 'r') as f:
    content = f.read()

# 移除不兼容的 bindings 字段
content = re.sub(r'"bindings":\s*\[.*?\]', '"bindings":[]', content)

with open('dist/_worker.js', 'w') as f:
    f.write(content)

构建命令可改为：

node ./node_modules/.bin/astro build && python3 fix_wrangler.py

---

版本日志

每次修改后务必更新 src/changelog.json，添加新版本条目：

{
  "version": "v0.0.23",
  "date": "2026-06-08",
  "changes": [
    "✨ 新增《文章标题》"
  ]
}

条目必须插在数组最前面（降序排列），图标会根据 change 文本关键词自动匹配：

• ✨ 新增/添加/支持/上线
• 🐛 修复/解决/修正
• 🎨 重设计/美化/样式/视觉
• ♻️ 重构/迁移/替换
• ⚡ 优化/调整/改进

---

常见问题

Q: 推送后线上没有更新？

检查 Cloudflare Pages 面板的构建日志，可能是构建失败。常见原因：Node 版本不匹配、依赖安装失败。

Q: 域名访问显示 Nginx 页面？

DNS 没有指向 Cloudflare Pages，而是解析到了服务器 IP。需要在域名 DNS 设置中将 CNAME 指向 Cloudflare Pages 分配的域名。

Q: 构建成功但页面空白？

检查 astro.config.mjs 中的 site 字段是否正确设置为 https://blog.lzplus.top，RSS 和 sitemap 依赖此配置。

MEDIA:/home/ubuntu/CloakBlog/src/content/blog/deploy-guide.md