安装并设置 Astro
create astro
CLI 命令 是从零开始创建一个新的 Astro 项目的最快方式。它将引导你完成设置新 Astro 项目的每一个步骤,并允许你从几个不同的官方起始模板中选择。
或者,你可以使用任何现有的主题或起始模板开始你的项目。
如果想要手动安装 Astro,请查看我们的逐步手动安装指南。
想在浏览器中尝试 Astro 吗?访问 astro.new 浏览我们的起始模板,并在不离开浏览器的情况下启动一个新的 Astro 项目。
前提条件
段落标题 前提条件- Node.js -
v18.17.1
或v20.3.0
或更高版本。(不支持v19
。) - 文本编辑器 - 我们推荐使用 VS Code 并安装我们的 官方 Astro 扩展。
- 终端 - Astro 通过其命令行界面(CLI)访问。
开始一个新项目
段落标题 开始一个新项目通过 CLI 向导安装
段落标题 通过 CLI 向导安装-
在你的终端运行以下命令以启动我们的便捷安装向导:
你可以在你的机器上的任何地方运行
create astro
,因此在开始之前无需创建一个新的空目录。如果你还没有为你的新项目准备一个空目录,向导将会自动为你创建一个。如果一切顺利,你将看到一个成功信息,随后是一些推荐的后续步骤。现在你的项目已经创建好了,你可以
cd
进入你的新项目目录开始使用 Astro。 -
如果你在 CLI 向导中跳过了
npm install
步骤,那么在继续之前请确保安装你的依赖。 -
现在你可以 启动 Astro 开发服务器 并在构建时看到你的项目的实时预览!
使用主题或起始模板
段落标题 使用主题或起始模板你也可以通过向 create astro
命令传递 --template
参数,基于 官方示例 或任何 GitHub 仓库的 main
分支开始一个新的 Astro 项目。
-
浏览我们的 主题和起始模板展示,在这里你可以浏览博客、作品集、文档站点、落地页等主题!或者在 GitHub 上搜索更多的起始项目。
-
在你的终端运行以下命令,替换官方 Astro 起始模板的名称,或你想使用的 GitHub 用户名和仓库:
默认情况下,此命令将使用模板仓库的
main
分支。如果要使用不同的分支名称,请在--template
参数中指定:<github-username>/<github-repo>#<branch>
。 -
回答 CLI 向导的问题并遵循其指示。
-
现在你可以 启动 Astro 开发服务器 并在自定义项目的同时查看实时预览!
手动设置
段落标题 手动设置本指南将指导你手动安装和配置新的 Astro 项目。
如果你不想使用我们的自动 create astro
CLI 工具,可以按照下面的指南自行设置你的项目。
-
创建你的目录
创建一个以你的项目命名的空目录,然后进入该目录。
进入你的新目录后,创建你的项目
package.json
文件。这是你管理项目依赖项(包括 Astro)的方式。如果你不熟悉这种文件格式,请运行以下命令创建一个。 -
安装 Astro
首先,在你的项目中安装 Astro 的依赖项。
Astro 必须安装在本地,不能全局安装。确保你没有运行
npm install -g astro
、pnpm add -g astro
或yarn add global astro
。然后,用以下内容替换你的
package.json
中的任何占位符 “scripts” 部分:你将在本指南后面使用这些脚本来启动 Astro 并运行其不同的命令。
-
创建你的第一个页面
在你的文本编辑器中,在你的目录下的
src/pages/index.astro
创建一个新文件。这将是你项目中的第一个 Astro 页面。对于本指南,请将以下代码片段(包括
---
破折号)复制并粘贴到你的新文件中: -
创建你的第一个静态资源
你还需要创建一个
public/
目录来存储你的静态资源。Astro 将始终在你的最终构建中包含这些资源,因此你可以安全地从你的组件模板中引用它们。在你的文本编辑器中,在你的目录下的
public/robots.txt
创建一个新文件。robots.txt
是大多数网站会包含的一个简单文件,用于告诉像 Google 这样的搜索机器人如何处理你的网站。对于本指南,请将以下代码片段复制并粘贴到你的新文件中:
-
创建
astro.config.mjs
Astro 使用
astro.config.mjs
进行配置。如果你不需要配置 Astro,这个文件是可选的,但你现在可能希望创建它。在你项目的根目录下创建
astro.config.mjs
,并将下面的代码复制到其中:如果你想在你的项目中包含 UI 框架组件,如 React、Svelte 等,或使用其他工具,如 Tailwind 或 Partytown,这里是你手动导入和配置集成的地方。
阅读 Astro 的 API 配置参考 以获取更多信息。
-
添加 TypeScript 支持
TypeScript 使用
tsconfig.json
进行配置。即使你不编写 TypeScript 代码,这个文件也很重要,以便工具(如 Astro 和 VS Code)了解你的项目。某些功能(如 npm 包导入)在没有tsconfig.json
文件的情况下在编辑器中不完全支持。如果你打算编写 TypeScript 代码,建议使用 Astro 的
strict
或strictest
模板。你可以在 astro/tsconfigs/ 查看并比较三种模板配置。在你项目的根目录下创建
tsconfig.json
,并将下面的代码复制到其中。(你可以使用base
、strict
或strictest
作为你的 TypeScript 模板):最后,创建
src/env.d.ts
,让 TypeScript 知道 Astro 项目中可用的环境类型:阅读 Astro 的 TypeScript 设置指南 以获取更多信息。
-
接下来
如果你已经按照上面的步骤操作,你的项目目录现在应该如下所示:
文件夹node_modules/
- …
文件夹public/
- robots.txt
文件夹src/
文件夹pages/
- index.astro
- env.d.ts
- astro.config.mjs
- package-lock.json 或
yarn.lock
、pnpm-lock.yaml
等。 - package.json
- tsconfig.json
-
现在你可以启动 Astro 开发服务器 并在构建项目的同时查看实时预览了!
启动 Astro 开发服务器
段落标题 启动 Astro 开发服务器Astro 自带了一个内置的开发服务器,它包含了项目开发所需的一切。astro dev
CLI 命令将启动本地开发服务器,让你第一次看到你的新网站。
每个起始模板都预配置了一个脚本,该脚本将为你运行 astro dev
。在进入你的项目目录后,使用你喜欢的包管理器运行此命令并启动 Astro 开发服务器。
如果一切顺利,Astro 将在 http://localhost:4321/ 上为你的项目提供服务。在浏览器中访问该链接,查看你的新网站!
开发模式工作
段落标题 开发模式工作Astro 将监听你的 src/
目录中的实时文件更改,并在你构建时更新你的网站预览,因此在开发过程中你无需重启服务器。当开发服务器运行时,你总能在浏览器中看到你网站的最新版本。
在浏览器中查看你的网站时,你将能够访问 Astro 开发工具栏。在你构建时,它将帮助你检查你的 群岛,发现无障碍问题等。
如果在启动开发服务器后无法在浏览器中打开你的项目,请返回运行 dev
命令的终端并检查显示的消息。它应该会告诉你是否发生了错误,或者你的项目是否在不同的 URL http://localhost:4321/ 上提供服务。
构建并预览你的网站
段落标题 构建并预览你的网站若要检查将在构建时创建的网站版本,请退出开发服务器(Ctrl + C)并在你的终端中运行适用于你的包管理器的相应构建命令:
Astro 将在一个单独的文件夹(默认为 dist/
)中构建你的网站的可部署版本,并且你可以在终端中看到其进度。这将在你部署到生产环境之前提醒你项目中的任何构建错误。如果 TypeScript 配置为 strict
或 strictest
,build
脚本还将检查你的项目中的类型错误。
当构建完成后,在你的终端中运行适当的 preview
命令(例如 npm run preview
),你就可以在同一个浏览器预览窗口中本地查看你的网站的构建版本。
请注意,这将预览你在最后一次运行构建命令时的代码状态。这旨在让你预览你的网站在 部署到网络 时的样子。在构建后对代码进行的任何更改都不会在你预览网站时反映出来,直到你再次运行构建命令。
使用(Ctrl + C)退出预览并在终端中运行另一个命令,例如重新启动开发服务器以返回 开发模式工作,它会随着你的编辑更新以显示你的代码更改的实时预览。
部署你的新网站
段落标题 部署你的新网站你可能希望 立即部署你的新网站,在你开始添加或更改太多代码之前。这有助于发布你的网站的最小工作版本,并可以节省你以后排查部署问题的时间和精力。
接下来
段落标题 接下来好了!你现在可以开始使用 Astro 构建了!🥳
以下是我们建议接下来探索的几个主题,你可以按任何顺序阅读它们。你甚至可以暂时离开我们的文档去玩转你的新 Astro 项目代码库,当你遇到麻烦或有疑问时,欢迎你随时返回这里。