首页 / Astro 教程 / 安装与环境准备：Node 与 create astro 脚手架

← 上一篇 下一篇 →
Astro 教程

安装与环境准备：Node 与 create astro 脚手架

本教程共 56 篇 · 第 4 篇 · 更新于 2026-08-07 · 约 8 分钟阅读

AstroAstro 教程安装Node.jscreate astro脚手架VS Code环境配置

本节目标：知道跑起 Astro 需要哪些工具，搞懂 Node 版本要求，并了解用官方脚手架 create astro 生成项目的标准流程。

前面三章都在讲「是什么、为什么」。从本章开始，我们为真正动手做准备。这一章只做一件事：把环境讲清楚。

Note

本章以「讲明白流程」为主，不要求你此刻就建一个完整项目。你只要知道每一步在做什么、命令怎么写，后面需要时照着走就行。

需要准备的三样东西

想用 Astro 建站，你的电脑上得先备齐三样基础工具：

  1. 终端（命令行）：用来敲命令创建项目、启动本地服务。Mac / Linux 上叫「终端」，Windows 上叫「命令提示符」或 PowerShell，安卓上可用 Termux。一般系统都自带。
  2. Node.js：Astro 跑在你的机器上需要一个 JavaScript 运行环境，这就是 Node.js。没有它，Astro 根本起不来。
  3. 代码编辑器：用来写代码的软件，最推荐 VS Code。

这三样里，终端基本现成，编辑器装一次就行，真正要留心的其实是 Node.js 的版本。

Node.js 版本有讲究

Astro 对 Node 版本有个「怪规矩」：只支持偶数版本。比如 v22、v24 这种。奇数版本（v23、v25）官方不保证能用。

截至 Astro 7.2.0，最低要求是 v22.12.0。

怎么确认自己装没装、装的是哪个版本？在终端里敲：

node -v

如果正常，它会回你一个版本号，比如：

v22.20.0

看到的是受支持的版本，就万事大吉。如果出现 Command 'node' not found 这种报错，或者版本号低于要求，就得先去装一个兼容的 Node.js。

Tip

装 Node 推荐用官网安装包，或者用 nvm 这类版本管理器。选「偶数大版本里较新的一个」最稳妥，比如 v22 系列的最新小版本。别图新鲜去装 v23、v25 这类奇数版，Astro 不一定认。

代码编辑器：首推 VS Code

编辑器随便挑，但 Astro 官方给 VS Code 做了专属插件，能帮你高亮语法、自动补全，体验最好。

  1. 去 VS Code 官网下载并安装。
  2. 打开 Astro 项目后，VS Code 通常会弹窗问你要不要装「推荐扩展」，里面就包含 Astro 语言支持插件。装上它，写 .astro 文件会舒服很多。

如果你习惯别的编辑器（比如 WebStorm、Neovim），也能用，只是少点官方定制的便利。

用 create astro 生成项目

环境齐了，下一步是「建一个新 Astro 项目」。Astro 官方提供了交互式向导 create astro，是最省事的办法。

在终端里，用你喜欢的包管理器运行这条命令（任选其一）：

# 用 npm
npm create astro@latest

# 用 pnpm
pnpm create astro@latest

# 用 yarn
yarn create astro

敲下回车后，向导会一步步问你问题。标准流程大概是这样：

  1. 终端提示是否安装 create-astro，输入 y 确认。
  2. 问「项目建在哪」，填一个文件夹名，向导会新建这个目录，比如 ./my-site。
  3. 出现一排起始模板让你选。用上下方向键移动到「空模板（minimal）」，回车确认。
  4. 问是否安装依赖，输入 y。
  5. 问是否初始化 git 仓库，输入 y。

跑完这几步，一个全新的 Astro 项目骨架就躺在你指定的文件夹里了。

Note

术语小卡片：包管理器是帮你下载、管理项目依赖（别人写好的代码库）的工具。npm、pnpm、yarn 都是，选一个顺手的即可。Astro 三者都支持，本书示例多用 npm。

在 VS Code 里打开项目

项目生成后，用 VS Code 打开那个文件夹：

  1. 打开 VS Code，选「打开文件夹」，指向向导刚建好的目录。
  2. 首次打开 Astro 项目，会看到安装推荐扩展的提示，点进去装上 Astro 语言支持插件。
  3. 确认 VS Code 底部的终端面板是可见的，后面我们就在它的终端里敲命令。

启动本地预览：dev 模式

项目里的文件只是「源代码」，浏览器负责把它们显示成网页。想边写边看效果，就得让 Astro 跑在「开发模式」（dev mode）。

在 VS Code 的终端里运行：

# npm
npm run dev

# pnpm
pnpm run dev

# yarn
yarn run dev

终端会显示 Astro 已启动。默认地址是 http://localhost:4321（端口被占时会自动换一个）。

点终端里的 localhost 链接，浏览器就会打开你的新网站预览。空模板打开后，是一张干净的白页，顶部写着 Astro。

Tip

dev 模式的好处是「热更新」：你改代码保存，浏览器自动刷新。写页面时基本离不开它。等网站写完了，才需要下面的「构建」步骤。

写完后怎么产出正式网站

dev 模式只是本地预览。真正要把网站发布出去，需要「构建」一步：

npm run build

构建完成后，成品会放进 dist/ 目录。把这个目录部署到任意静态托管平台（Netlify、Vercel、GitHub Pages 等）即可上线。

如果你的网站需要按访问实时生成页面（按需渲染），得先装一个对应的适配器（adapter），比如：

npx astro add netlify

astro add 命令会帮你把适配器装好、并自动写进配置文件。不同平台有不同适配器，选你打算部署的那家就行。

Note

部署和适配器属于「上线阶段」的事，本书这里只点一下，不展开。等后面讲到按需渲染和部署章节，会细说。

动手前确认一下是否装好了

环境装完，最好做个「冒烟测试」，免得后面卡在低级错误上。三样工具分别自查一遍：

  1. 终端：能正常打开、能敲命令就行，一般系统自带，无需特别验证。
  2. Node.js：运行 node -v，能回出版本号且是偶数大版本（如 v22.x），就过关。
  3. 包管理器：运行 npm -v（或 pnpm -v / yarn -v），能看到版本号，说明装好了。

如果哪一步报「命令找不到」，多半是没装或者没加进系统路径。重装对应工具、重启终端通常能解决。

Tip

包管理器三者选一即可，不用全装。本书示例统一用 npm，因为它随 Node.js 一起装好，新人最省心。等熟练了，想换 pnpm 提速也很容易，命令几乎一一对应。

小结

这一章把环境这条线理清楚了：

  1. 三样基础工具：终端、Node.js、代码编辑器。
  2. Node 认偶数版本，最低 v22.12.0，用 node -v 自查。
  3. 用 npm create astro@latest 走向导生成项目骨架。
  4. 装 VS Code + Astro 插件，用 npm run dev 看本地预览。
  5. 正式发布用 npm run build，产物在 dist/；按需渲染要先加适配器。

下一章，我们进到生成好的项目里，看清每个文件夹、每个文件到底是干什么的。

上一篇
Astro 适用场景：能做什么、不能做什么
下一篇
项目结构与核心文件