Astro博客部署踩坑记录#

哎哟喂，本宫这博客，刚在皇上那儿得了些脸，就有人巴巴地跑来问Astro部署的事儿。本宫一想，得了，佛口婆心一回，把本宫当初摔的跟头、碰的钉子，都掰碎了喂给你们。可记好了，本宫只教一遍，听不明白的，自己去墙角面壁去！

一、路径错乱：你以为的根目录，不是你以为的根目录

啧，你们这帮小傻瓜，总以为npm run build一声令下就万事大吉？天真！本宫当初就是在本地看得好好的，一部署上去，嘿，样式全没了，图片也裂了，那页面丑得本宫差点没认出来。问题出在哪儿？astro.config.mjs里那个site和base配置！

皇上给你开的是子目录，比如/blog/，你却非要让全站从/开始找东西，这不乱套了吗？记住了，base选项必须填上你部署的子路径。要是直接挂在根目录下，那就留空。这玩意儿要是弄错，你那站就等着在404的海洋里漂着吧，跟没了魂儿似的。

二、依赖报错：那红通通的Error看得本宫心口疼

npm install跑着跑着，突然就给你甩一串红色警告，或者干脆卡住不动？本宫最烦这个。十个有八个，是Node.js版本的问题。Astro对这个挑食得很，你机器上装的可能是古董版，也可能是尝鲜版，都不是它要的。

先用node -v看看自己装的是个啥。别瞎折腾了，直接上nvm（Node Version Manager）管理版本，按Astro官方推荐的来，一般是18.x或者20.x。切换干净了，删了node_modules和package-lock.json，再来一次npm install，世界立马就清静了。听本宫的，省得你在那对着屏幕骂街。

三、部署后白屏或样式全丢：又是路径的锅

本宫知道你们急着看效果，可有些坑它就是绕不过去。比如，你用的是Vercel、Netlify这些自动部署的，有时候它们会“聪明地”帮你处理路径，结果反而帮了倒忙。

去你的部署平台设置里，好好看看build command和output directory对不对。Astro默认是npm run build和dist，别手滑改了。还有，如果你用了动态路由（比如[slug].astro），确保在构建时这些路径能被正确生成。不然部署上去，要么是404，要么是空白一片，跟本宫没打扮就见皇上似的，惨不忍睹。

四、图片加载慢得像乌龟爬

哦？你的博客图片多？那可得小心了。Astro默认的<Image>组件已经很智能了，会自动生成WebP和响应式尺寸。但如果你还是用了老式的<img>标签，或者把几百KB的大图原封不动扔进去，那你那博客的加载速度，慢得能让皇上等到睡着。

记得用好Astro的<Image>组件，配合@astrojs/image（注意，Astro 3.0后集成方式有变，去翻最新文档！）。在astro.config.mjs里配置好图片优化服务（比如sharp或者squash）。虽然本宫觉得这些琐碎事很烦人，但为了你那金贵的访客体验，忍忍吧。

五、SSG还是SSR？别选错了路哭鼻子

“本宫全都要！”——你以为你是皇上啊？Astro支持静态站点生成（SSG）和服务端渲染（SSR），但你得在astro.config.mjs里用output: 'static'（默认）或output: 'server'明确告诉它。

选SSG，内容在构建时就生成好了，快，省事，但没法用需要服务器实时处理的功能（比如某些带登录态的交互）。选SSR，则需要一个Node.js环境，能用所有功能，但部署复杂点，还要注意服务器配置。本宫当初就没想清楚，结果构建出来的站，少了动态功能，又得推倒重来，气得本宫肝疼。你自己掰着指头算算，到底要什么，别贪心。

六、最终幻想：部署完成就当甩手掌柜？

想得美！本宫告诉你，部署成功只是万里长征第一步。你得去点开你的站点，每一个链接都点一遍，每一张图都看看，每一个功能都试一试。特别是用了动态路由和内容集合的，去检查一下生成的每一页是不是都健在。

还有，去浏览器控制台（F12）里瞄一眼，看看有没有报错。有些资源加载失败的小问题，页面上不明显，但控制台里红得扎眼。别等读者来反馈，那多丢本宫的脸。

好了，本宫的碎碎念到这儿。这些坑，本宫替你们踩过了，你们要是还往里跳，那本宫也只能在旁边嗑着瓜子，笑你一声“活该”了。毕竟，能教会小傻瓜的，从来不是教程，是南墙。祝各位，早日把博客部署得稳稳当当，好让本宫也去逛逛，挑挑刺儿。