安装并设置 Astro

create astro CLI 命令是从零开始创建一个新的 Astro 项目的最快方式。它将引导你完成设置新 Astro 项目的每一个步骤，并允许你从几个不同的官方起始模板中选择。

或者，你可以使用任何现有的主题或起始模板开始你的项目。

如果想要手动安装 Astro，请查看我们的逐步手动安装指南。

前提条件

Node.js - v18.17.1 或 v20.3.0 或更高版本。（不支持 v19。）
文本编辑器 - 我们推荐使用 VS Code 并安装我们的官方 Astro 扩展。
终端 - Astro 通过其命令行界面（CLI）访问。

开始一个新项目

通过 CLI 向导安装

在你的终端运行以下命令以启动我们的便捷安装向导：
- npm
- pnpm
- yarn
Terminal window
# 使用 npm 创建一个新项目 npm create astro@latest
Terminal window
# 使用 pnpm 创建一个新项目 pnpm create astro@latest
Terminal window
# 使用 yarn 创建一个新项目 yarn create astro
你可以在你的机器上的任何地方运行 create astro，因此在开始之前无需创建一个新的空目录。如果你还没有为你的新项目准备一个空目录，向导将会自动为你创建一个。

如果一切顺利，你将看到一个成功信息，随后是一些推荐的后续步骤。现在你的项目已经创建好了，你可以 cd 进入你的新项目目录开始使用 Astro。
如果你在 CLI 向导中跳过了 npm install 步骤，那么在继续之前请确保安装你的依赖。
现在你可以启动 Astro 开发服务器并在构建时看到你的项目的实时预览！

使用主题或起始模板

你也可以通过向 create astro 命令传递 --template 参数，基于官方示例或任何 GitHub 仓库的 main 分支开始一个新的 Astro 项目。

浏览我们的主题和起始模板展示，在这里你可以浏览博客、作品集、文档站点、落地页等主题！或者在 GitHub 上搜索更多的起始项目。

在你的终端运行以下命令，替换官方 Astro 起始模板的名称，或你想使用的 GitHub 用户名和仓库：

# 使用官方示例创建一个新项目
npm create astro@latest -- --template <example-name>

# 基于 GitHub 仓库的 main 分支创建一个新项目
npm create astro@latest -- --template <github-username>/<github-repo>

# 使用官方示例创建一个新项目
pnpm create astro@latest --template <example-name>

# 基于 GitHub 仓库的 main 分支创建一个新项目
pnpm create astro@latest --template <github-username>/<github-repo>

# 使用官方示例创建一个新项目
yarn create astro --template <example-name>

# 基于 GitHub 仓库的 main 分支创建一个新项目
yarn create astro --template <github-username>/<github-repo>

默认情况下，此命令将使用模板仓库的 main 分支。如果要使用不同的分支名称，请在 --template 参数中指定：<github-username>/<github-repo>#<branch>。

回答 CLI 向导的问题并遵循其指示。
现在你可以启动 Astro 开发服务器并在自定义项目的同时查看实时预览！

手动设置

本指南将指导你手动安装和配置新的 Astro 项目。

如果你不想使用我们的自动 create astro CLI 工具，可以按照下面的指南自行设置你的项目。

创建你的目录

创建一个以你的项目命名的空目录，然后进入该目录。
Terminal window
```
mkdir my-astro-project
cd my-astro-project
```
进入你的新目录后，创建你的项目 package.json 文件。这是你管理项目依赖项（包括 Astro）的方式。如果你不熟悉这种文件格式，请运行以下命令创建一个。
- npm
- pnpm
- yarn
Terminal window
npm init --yes
Terminal window
pnpm init
Terminal window
yarn init --yes
安装 Astro

首先，在你的项目中安装 Astro 的依赖项。

Astro 必须安装在本地，不能全局安装。确保你没有运行 npm install -g astro、pnpm add -g astro 或 yarn add global astro。
- npm
- pnpm
- yarn
Terminal window
npm install astro
Terminal window
pnpm add astro
Terminal window
yarn add astro
然后，用以下内容替换你的 package.json 中的任何占位符 “scripts” 部分：
package.json
```
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  },
```
你将在本指南后面使用这些脚本来启动 Astro 并运行其不同的命令。

创建你的第一个页面

在你的文本编辑器中，在你的目录下的 src/pages/index.astro 创建一个新文件。这将是你项目中的第一个 Astro 页面。

对于本指南，请将以下代码片段（包括 --- 破折号）复制并粘贴到你的新文件中：

---
// 欢迎使用 Astro！这些三破折号代码围栏之间的内容是你的 "component frontmatter"。它不会在浏览器中运行。
console.log('这段代码在你的终端运行，而不是在浏览器中！');
---
<!-- 下面是你的 "component template"。它只是 HTML，但加入了一些魔法，帮助你构建出色的模板。 -->
<html>
  <body>
    <h1>Hello, World!</h1>
  </body>
</html>
<style>
  h1 {
    color: orange;
  }
</style>

创建你的第一个静态资源

你还需要创建一个 public/ 目录来存储你的静态资源。Astro 将始终在你的最终构建中包含这些资源，因此你可以安全地从你的组件模板中引用它们。

在你的文本编辑器中，在你的目录下的 public/robots.txt 创建一个新文件。robots.txt 是大多数网站会包含的一个简单文件，用于告诉像 Google 这样的搜索机器人如何处理你的网站。

对于本指南，请将以下代码片段复制并粘贴到你的新文件中：
public/robots.txt
```
# 示例：允许所有机器人扫描并索引你的网站。
# 完整语法：https://developers.google.com/search/docs/advanced/robots/create-robots-txt
User-agent: *
Allow: /
```
创建 astro.config.mjs

Astro 使用 astro.config.mjs 进行配置。如果你不需要配置 Astro，这个文件是可选的，但你现在可能希望创建它。

在你项目的根目录下创建 astro.config.mjs，并将下面的代码复制到其中：
astro.config.mjs
```
import { defineConfig } from 'astro/config';

// https://astro.build/config
export default defineConfig({});
```
如果你想在你的项目中包含 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 模板）：
tsconfig.json
```
{
  "extends": "astro/tsconfigs/base"
}
```
最后，创建 src/env.d.ts，让 TypeScript 知道 Astro 项目中可用的环境类型：
src/env.d.ts
```
/// <reference types="astro/client" />
```
阅读 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 dev CLI 命令将启动本地开发服务器，让你第一次看到你的新网站。

每个起始模板都预配置了一个脚本，该脚本将为你运行 astro dev。在进入你的项目目录后，使用你喜欢的包管理器运行此命令并启动 Astro 开发服务器。

npm run dev

pnpm run dev

yarn run dev

如果一切顺利，Astro 将在 http://localhost:4321/ 上为你的项目提供服务。在浏览器中访问该链接，查看你的新网站！

开发模式工作

Astro 将监听你的 src/ 目录中的实时文件更改，并在你构建时更新你的网站预览，因此在开发过程中你无需重启服务器。当开发服务器运行时，你总能在浏览器中看到你网站的最新版本。

在浏览器中查看你的网站时，你将能够访问 Astro 开发工具栏。在你构建时，它将帮助你检查你的群岛，发现无障碍问题等。

如果在启动开发服务器后无法在浏览器中打开你的项目，请返回运行 dev 命令的终端并检查显示的消息。它应该会告诉你是否发生了错误，或者你的项目是否在不同的 URL http://localhost:4321/ 上提供服务。

构建并预览你的网站

若要检查将在构建时创建的网站版本，请退出开发服务器（Ctrl + C）并在你的终端中运行适用于你的包管理器的相应构建命令：

npm run build

pnpm build

yarn run build

Astro 将在一个单独的文件夹（默认为 dist/）中构建你的网站的可部署版本，并且你可以在终端中看到其进度。这将在你部署到生产环境之前提醒你项目中的任何构建错误。如果 TypeScript 配置为 strict 或 strictest，build 脚本还将检查你的项目中的类型错误。

当构建完成后，在你的终端中运行适当的 preview 命令（例如 npm run preview），你就可以在同一个浏览器预览窗口中本地查看你的网站的构建版本。

请注意，这将预览你在最后一次运行构建命令时的代码状态。这旨在让你预览你的网站在部署到网络时的样子。在构建后对代码进行的任何更改都不会在你预览网站时反映出来，直到你再次运行构建命令。

使用（Ctrl + C）退出预览并在终端中运行另一个命令，例如重新启动开发服务器以返回开发模式工作，它会随着你的编辑更新以显示你的代码更改的实时预览。

阅读更多关于 Astro CLI 和你在使用 Astro 构建时将使用的终端命令。

部署你的新网站

你可能希望立即部署你的新网站，在你开始添加或更改太多代码之前。这有助于发布你的网站的最小工作版本，并可以节省你以后排查部署问题的时间和精力。

接下来

好了！你现在可以开始使用 Astro 构建了！🥳

以下是我们建议接下来探索的几个主题，你可以按任何顺序阅读它们。你甚至可以暂时离开我们的文档去玩转你的新 Astro 项目代码库，当你遇到麻烦或有疑问时，欢迎你随时返回这里。

探索 Astro 的特性

了解你的代码库在我们的项目结构指南中了解 Astro 的文件结构。

创建内容集合通过 frontmatter 验证和自动类型安全向你的新网站添加内容。

添加视图过渡创建无缝页面过渡和动画。

了解群岛阅读关于 Astro 的群岛结构。

配置你的开发环境

编辑器设置自定义你的代码编辑器以改善 Astro 开发者体验并解锁新功能。

TypeScript 配置 Astro 的内置 TypeScript 支持，是严格还是宽松都随你喜好！

导入别名为你的文件导入创建方便的快捷方式。

环境变量在你的项目中设置和使用环境变量。

开发工具栏探索开发工具栏中好用的功能。

创建 GitHub Issue

发送反馈