使用指南 8:把博客发布到自己的域名
确认网站地址,完成本地检查和图片准备,再部署静态文件、绑定域名并核对结果。
文章目录
版本说明: 正常 build/CI doctor 自动补齐图片需要主题 0.36.2 或更新版本;0.36.1 需先运行 dev 或 prepare-covers。显式 prepare-covers --check 保持只读。
本篇是入门教程的第 8 / 8 篇。查看完整教程顺序 · 按字段查配置字典。
本地已经能打开博客后,发布需要做三件事:确认最终域名、生成完整静态文件、让托管服务用这个域名提供这些文件。主题不会替你购买域名、修改 DNS 或自动登录托管平台。
当前 starter 默认构建静态网站,不需要生产环境一直运行 Node.js,也不需要为了发布静态页面添加 SSR adapter。下面以 npm 项目和默认输出目录 dist/ 为例。
1. 先确定正式网站地址
准备一个由自己管理的域名,例如 https://blog.example.com。在 src/site.config.ts 现有顶层 site 中合并:
site: {
url: 'https://blog.example.com',
},
填写最终对外访问的地址,不填 localhost、某篇文章的网址或托管控制台地址。其他站点信息保留不变。
这个值会用于生成 canonical、RSS、sitemap、分享图和公开内容链接。它不改变本地开发服务地址,也不会把一个尚未绑定的域名自动指向网站。
检查有没有旧的环境覆盖
如果项目 .env、适用的 .env.* 文件或托管构建环境中设置了 PUBLIC_SITE_URL,它优先于配置文件。只改 site.url 但结果仍是旧域名时,应同时检查这些位置。普通 dev 使用 development 模式,普通 build 使用 production 模式;自定义 --mode 时还会读取对应模式配置,不能只检查 .env。
不需要环境覆盖就移除对应变量,统一使用 site.url;需要区分环境时,在各自构建环境设置正确值。修改后重新构建,不能只在旧产物里手动改一个链接。
使用域名根目录
当前主题按域名根目录部署使用,例如 https://blog.example.com/。部署到 https://example.com/my-blog/ 这种子路径仍需额外适配,不能只设置 Astro base 就认为全部页面和资源都兼容。
选择托管方式时确认它能提供根目录站点、静态目录的 index.html 和正常的子页面路径。如果使用 GitHub Pages,优先按它的站点域名/自定义域名流程部署,不能直接把项目子路径教程当作本主题已经支持的配置。平台具体设置参见 Astro 部署文档及其中对应的托管指南。
2. 把需要的源文件准备完整
部署应使用你自己的博客项目及实际内容所在分支,不是把主题维护仓库的演示内容直接当成个人博客。源码至少包含项目配置、内容、依赖清单和需要的资源。
新增或替换本地封面、碎片图片后,先在本地 dev 或 doctor 中准备响应式文件,再提交:
- 文章、碎片、自建页面和
src/site.config.ts。 - 文章引用的原图、public 图片、图标和实际需要的音乐等资源。
- 整个
src/assets/blog/covers/,包括 manifest.json、generated/ 和使用到的 originals/。 package.json、package-lock.json,以及项目原有 Astro 配置和托管设置。
原图不一定放在 originals:放在文章旁边或 public 中的原文件也要提交。图片准备细节见给文章和碎片添加图片。
部署端的普通 build 会自动补齐缺失、过期或损坏的响应式图片,CI doctor 同样会准备。 有效派生文件直接复用;原图缺失、无法解码或路径越界仍会报错。提交派生文件可加快后续构建,但不再是正常 build 成功的前提,也不需要部署平台保留图片缓存。
基于 Git 构建的部署不需要提交 node_modules、.astro 或 dist;平台会安装依赖并生成产物。不要把本机的依赖目录作为静态网站上传。环境文件若没有进入仓库,在平台上配置需要的环境变量;PUBLIC_ 变量用于公开站点信息,不适合存放私密凭据。
3. 本地检查并预览真正的构建结果
先按 Ctrl+C 停止 dev,确保当前终端位于项目根目录,然后运行:
npm run doctor
npm run preview
打开 preview 打印的网址,检查首页、文章、图片、语言菜单和文章搜索。新增语言或开启可选页面时,也检查它们的入口。评论等外部服务需要浏览器实际连接才能确认,本地构建通过不会证明远程权限配置正确。
这些命令的职责不同:
| 命令 | 做什么 |
|---|---|
npm run dev |
本地开发,相关图片可自动准备;没有构建后的全文搜索索引 |
npm run doctor |
本地准备图片,执行 Astro 检查和构建;About 开启时还检查其运行时配置 |
npm run check |
当前 starter 中同样调用 doctor,不必与 doctor 连续重复执行 |
npm run build |
准备需要的持久图片并构建网站,不执行 doctor 的其他检查 |
npm run preview |
提供已经构建的 dist,不重新构建、不发布网站 |
任何检查或构建失败时先修复错误,不要部署残留 dist。doctor 成功后已有构建结果,无需紧接着再执行 check 和 build。preview 按 Ctrl+C 停止。
4. 部署完整静态产物
你可以连接 Git 仓库让平台构建,也可以本地构建后手动上传。两种方式最终都提供同一份静态输出。
方式一:托管平台从 Git 构建
在所选平台连接自己的仓库,并配置:
| 项目 | 当前 starter 的设置 |
|---|---|
| 构建分支 | 你实际维护博客内容的分支 |
| 项目根目录 | 包含该博客 package.json 的目录,不一定是整个仓库最外层 |
| Node.js | 满足项目和依赖要求,当前 starter 声明 22.12.0 或更新版本 |
| 安装 | npm 项目可使用 npm ci,需要已提交且与 package.json 一致的 package-lock.json |
| 构建命令 | npm run build |
| 输出目录 | dist,相对于项目根目录 |
如果平台自动执行依赖安装,不必重复添加一次安装命令;如果要求自己写完整构建脚本,应先安装再 build。不要在构建脚本里重复运行 doctor、check、build,无需另加图片补生成步骤;正常 build 已统一处理派生资源,但原图必须提交。
平台的框架预设、分支和安装步骤以它的实际设置为准。选择静态输出方式,不需要把 npm run dev 或 npm run preview 作为生产启动命令。
方式二:上传本地构建结果
本地 doctor 成功后,将 dist/ 的全部内容上传到托管服务的网站根目录。如果服务让你选择输出文件夹,就选择 dist;如果让你上传网站文件,就上传 dist 里面的内容,不要额外多套一层 dist 路径。
除 HTML 外,还要包含 _astro/、_blog-covers/、_social/、搜索索引以及本次构建实际生成的其他文件。以下划线开头的目录不是可以忽略的临时文件;只传 HTML 会导致样式、脚本、图片或搜索缺失。
重新发布时使用平台的完整部署/替换机制,避免只覆盖新文件却留下已删除文章、旧分页或旧语言文件。删除本地 Markdown 不会让手动上传服务器上的旧 HTML 自动消失。
5. 在平台绑定域名,再配置 DNS
在托管平台中添加要使用的自定义域名,然后按它提供的记录值,在域名 DNS 管理处添加或修改记录。根域名与子域名的记录类型及目标可能不同,应使用平台给出的实际值,不要照抄示例 IP。
等待平台确认域名及 HTTPS 证书可用,再通过正式地址打开网站。若同时使用裸域名和 www 等多个地址,选择一个作为主地址,并在托管侧将其他地址重定向到它,site.url 也填写主地址。
canonical 只是页面元信息,不是访问重定向。主题中的 site.url 不会替你执行 DNS、证书签发或多域名跳转;这些由域名和托管设置负责。更换主域名后重新构建并部署,更新仍保留旧域名的环境覆盖值。
6. 发布后核对页面和公开输出
通过正式域名检查一篇文章的直接链接,刷新后也应能打开;不能只从首页点进去成功就认为所有路径都正确。再检查图片、代码样式、语言切换和搜索。仅在 dev 中测试过的功能,需要在已构建网站上重新确认。
主题默认接入这些静态输出,不需要再安装一套相同集成:
| 地址示例 | 用途 |
|---|---|
/robots.txt |
提供抓取规则及 sitemap 地址,不是访问权限控制 |
/sitemap-index.xml |
站点地图入口,链接应使用正式域名 |
/zh/rss.xml |
中文文章订阅,其他启用语言替换 zh |
/llms.txt |
AI 可读内容总索引 |
/zh/llms.txt、/zh/llms-full.txt |
该语言有导出内容时的索引与全文合集 |
/zh/blog/my-first-post/index.md |
对应公开文章的 Markdown 输出,示例 slug 换成真实文章 |
/zh/fragments/index.md、/zh/about/index.md |
对应页面启用且符合导出条件时的公开内容 |
文章 sitemap 更新日期使用 updatedDate,未填时使用 pubDate,不会每次构建伪造新日期。关闭的语言/页面不应期待有对应公开导出;文章搜索的 search: false 不等于文章私密,也不会自动禁止其他公开输出。
AI 导出包含公开文章、启用的 Fragments 和 About 内容;评论和装饰工具界面不在导出正文中。实际 noindex 页面或站外 canonical 页面不纳入导出,用户自有文件与生成路径冲突时会停止构建,不会直接覆盖。导出文件和发现链接随重新构建更新,需要一起部署。
这些元信息与文本输出有助于发现和读取,不保证搜索引擎收录、AI 引用或流量增长。
托管响应头的区别
构建会在 dist/_headers 中为 /:locale/terminal/* 补充 X-Robots-Tag: noindex,保留已有规则,不修改源 public/_headers。支持这种文件格式的托管服务会应用它;其他服务需要等效响应头设置。
Astro preview 不会模拟托管平台的 _headers 规则。要判断响应头是否生效,应检查正式服务的响应,不能只看本地文件存在;无需为了这条规则添加 Node 服务器。
域名与环境变量的具体优先级见站点字典,公开说明的逐字段定义见GA4 与 AI 阅读补充字典。
7. 按需补充 AI 阅读说明
普通发布无需增加这项配置。如果想说明站点背景或提供额外资料,可以在配置顶层合并:
aiReadableContent: {
notes: '本站记录个人学习过程,内容可能持续修订。',
links: [{ label: '项目主页', href: 'https://example.com/project' }],
},
notes 支持 Markdown,links 每项填写 label 和 href。链接应为可公开访问的 HTTP(S) 地址;根路径等相对地址会按站点地址解析。这是公开的站点补充说明,不替换文章正文,也不是给文章增加隐私限制。
按语言覆盖时,使用 i18n.locales.<代码>.aiReadableContent。例如让中文使用自己的说明且不列附加链接:
i18n: {
locales: {
zh: {
aiReadableContent: {
notes: '中文内容是作者自己的学习笔记。',
links: [],
},
},
},
},
省略某个字段继承全局值;notes: ‘’ 或 links: [] 明确隐藏对应部分。补充说明会进入相关索引、全文合集和单篇 Markdown,填写前确认愿意公开,修改后重新构建。
8. 按需启用 GA4 访问统计
默认不加载 Google 统计脚本。需要统计时,先在 Google Analytics 的网页数据流中取得以 G- 开头的 Measurement ID;查找位置可参考 Google 官方说明。主题只接受 G- 形式的 ID,不使用数字属性 ID、GTM 容器 ID或其他标识代替。
在配置顶层、与 site 同一级,合并:
analytics: {
googleAnalyticsId: 'G-XXXXXXXXXX',
},
替换成真实 ID;空字符串关闭。格式错误会报配置错误。一个 ID 可以统计各语言页面,按路径区分语言即可;不必每种主题或语言粘一份脚本。
主题只在生产构建且已配置 ID 时输出加载器,dev 不发送。浏览器访问 localhost、其子域或回环等本地地址时,加载器跳过上报;使用局域网 IP 或远程预览域名访问生产构建则可能上报,不要把所有 preview 都当作被排除。
重新部署后,用正式地址访问并查看 GA4 实时报告。脚本拦截、网络和统计端设置都可能影响结果。不要同时用手工代码、GTM 或其他注入工具重复安装同一统计;本功能没有附带同意管理界面,需要时应自行接入相应方案。
9. 部署失败或线上不对时
| 现象 | 优先检查 |
|---|---|
| npm ci 失败 | Node/依赖要求,以及 package-lock 是否提交并与 package.json 一致 |
| 提示图片 missing/stale/modified | 确认原图已提交且路径合法;正常 build 会补齐派生文件,–check 只读检查需先准备 |
| 构建成功但页面 404 | 输出目录、发布分支、网站根目录和目录 index 支持;是否误用未适配的子路径 |
| 首页能开,文章刷新 404 | 平台是否提供真实静态子路径,是否错误地只发布首页或套用 SPA 回退 |
| 页面没样式、图片或搜索 | 是否完整部署 dist,资源子目录是否遗漏,路径是否被改写 |
| canonical/RSS 仍是示例域名 | site.url、PUBLIC_SITE_URL 及构建模式的环境值,是否重新构建部署 |
| 改配置后线上没变化 | 是否部署了正确项目、分支和最新提交,而不是只修改本机文件 |
| 删除文章后旧链接还能访问 | 是否仍残留旧部署文件或缓存;检查完整替换与托管缓存 |
| GA4 没有数据 | 是否配置真实 G- ID、使用生产构建和非本地地址,脚本是否被拦截 |
日常更新继续遵循“本地编辑与准备 → 检查预览 → 提交源文件 → 构建部署”。升级主题见安装教程,语言路径见让更多语言的读者使用博客。
教程导航与配置查阅
首次发布到这里完成。以后可按要修改的内容回看对应教程或查询配置字典。
本篇相关字段:域名与环境覆盖、GA4 与 AI 阅读补充、搜索资源。完整路径、默认值和限制见配置字典总入口。