Astro 是一个专为内容型网站设计的前端框架，默认输出纯静态 HTML，几乎不向浏览器发送 JavaScript，因此非常适合搭建博客、文档站、企业官网。相比传统的 Hexo 或 Hugo，Astro 支持在项目中直接使用 React、Vue 组件，灵活性更高。本文将在 Ubuntu 环境下完整演示 Astro 站点的配置流程，从环境准备一直讲到构建部署，把中间容易踩坑的地方都说明白。
一、准备 Node.js 运行环境
Astro 依赖 Node.js 运行，官方要求版本不低于 18.14.1。Ubuntu 仓库自带的 Node 版本往往偏旧，不建议直接用 apt 安装，推荐通过 NodeSource 源或 nvm 来安装新版本。
以 NodeSource 为例，安装 Node 20 LTS 的命令如下：
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs
安装完成后执行 node -v 和 npm -v 验证版本。如果提示 curl 不存在，先执行 sudo apt update && sudo apt install -y curl 补齐基础工具。若你的服务器上已有旧版 Node，建议先卸载干净再装，避免 npm install 时出现奇怪的二进制兼容问题。
另外建议把 npm 的全局安装目录切换到用户目录下，避免以后全局安装工具时反复使用 sudo。可以通过 npm config set prefix ~/.npm-global 设置，再把对应的 bin 目录追加到 PATH 环境变量中。这一步不是必须的，但能减少后续权限相关的麻烦。
二、创建 Astro 项目并理解目录结构
环境就绪后，在一个合适的目录执行创建命令：
npm create astro@latest my-site cd my-site npm install npm run dev
创建过程中脚手架会询问模板类型、是否使用 TypeScript 以及包管理器，初学者选最小模板加严格 TypeScript 即可。执行 npm run dev 后默认监听 4321 端口，如果是在远程服务器上开发，需要加 --host 参数让监听地址变成 0.0.0.0，否则本地浏览器无法访问。修改 package.json 中的 dev 脚本即可：
{
"scripts": {
"dev": "astro dev --host",
"build": "astro build",
"preview": "astro preview --host"
}
}
生成的项目目录中，src/pages 是路由目录，文件路径直接映射为 URL；src/content 存放 Markdown 内容；src/layouts 放布局组件；public 存放不参与构建处理的静态文件；根目录的 astro.config.mjs 是核心配置文件。理解这套约定对后面写页面很关键。
三、配置内容集合与文章模板
Astro 2.0 之后引入了 Content Collections，用来管理 Markdown 内容的类型与校验。在 src/content/config.ts 中定义集合：
import { defineCollection, z } from 'astro:content';
import { glob } from 'astro/loaders';
const blog = defineCollection({
loader: glob({ pattern: '**/*.md', base: './src/content/blog' }),
schema: z.object({
title: z.string(),
pubDate: z.date(),
description: z.string().optional(),
tags: z.array(z.string()).default([])
})
});
export const collections = { blog };
这样每篇文章的 frontmatter 都会被 schema 校验，字段写错或缺失会在构建时直接报错，比事后人工检查可靠得多。接着在 src/content/blog 下新建 Markdown 文件，顶部用三条横线包裹元信息：
--- title: 第一篇文章 pubDate: 2024-06-01 tags: ["随笔", "技术"] --- 正文内容，支持标准 Markdown 语法。
列表页和详情页可以通过 getCollection 和 render 两个 API 拿到数据并渲染。文章详情页建议放在 src/pages/blog/[slug].astro，配合动态路由实现一篇一个页面的效果。
四、构建产物部署到 Nginx
开发完成后执行 npm run build，产物默认输出到 dist 目录，全部是静态文件。生产环境推荐用 Nginx 托管，先安装：
sudo apt install -y nginx sudo cp -r ~/my-site/dist/* /var/www/html/
然后在 /etc/nginx/sites-available/default 中调整 server 配置，重点是静态资源缓存和 HTML 不缓存的区分：
server {
listen 80;
server_name example.ipipp.com;
root /var/www/html;
index index.html;
location ~* \.(js|css|png|jpg|webp|woff2)$ {
expires 30d;
add_header Cache-Control "public, immutable";
}
location / {
try_files $uri $uri/ $uri.html /404.html;
}
}
Astro 构建出的 js 和 css 文件名带哈希值，可以放心设置长缓存；而 HTML 文件必须保证及时更新，所以不要对它设长缓存。配置完成后执行 sudo nginx -t 检查语法，再 sudo systemctl reload nginx 生效。
如果站点需要经常更新，可以写一个简单的部署脚本，把 git pull、npm install、npm run build 和文件拷贝串起来，每次发文只需执行一次脚本。进一步还可以配合 GitHub Actions 实现推送代码后自动构建并同步到服务器，整个发布流程就完全自动化了。
五、常见问题排查
部署过程中有几个高频问题值得注意。一是访问页面返回 404，多半是 try_files 没有正确兜底，或者构建时页面路径与访问路径不一致，检查 dist 目录里的实际文件名即可定位。二是构建时报错 Cannot find module 'astro:content'，通常是 Node 版本过低或者依赖没装完整，删掉 node_modules 和 lock 文件重装一般能解决。
三是图片资源体积过大影响加载，Astro 内置的 <Image /> 组件会自动做格式转换和尺寸压缩，建议把图片放进 src/assets 目录用组件引用，而不是直接丢进 public 目录。四是端口被占用导致 dev server 启动失败，用 lsof -i :4321 查出占用进程再处理，或者通过 --port 换一个端口。
整体来看，Astro 在 Ubuntu 上的配置门槛并不高，核心工作集中在内容集合定义和 Nginx 缓存策略这两块。把这两处配置好后，一个加载速度快、维护成本低的内容站点就基本成型了，后续要做的只是持续写作和发布。