安装 Astro

create astro CLI 命令是从头开始一个新 Astro 项目的最快方法。它将引导你完成设置新 Astro 项目的每一步，并允许你从几个不同的官方入门模板中进行选择。

你也可以使用 template 标志运行 CLI 命令，以使用任何现有的主题或入门模板来开始你的项目。探索我们的主题和入门模板展示，在那里你可以浏览博客、作品集、文档网站、着陆页等主题！

要手动安装 Astro，请参阅我们的分步手动安装指南。

先决条件

Node.js - v18.20.8 或 v20.3.0、v22.0.0 或更高版本。（不支持 v19 和 v21。）
文本编辑器 - 我们推荐 VS Code 以及我们的官方 Astro 扩展。
终端 - Astro 通过其命令行界面（CLI）进行访问。

浏览器兼容性

Astro 是用 Vite 构建的，默认情况下，它支持具有现代 JavaScript 功能的浏览器。要获取完整的参考，你可以查看 Vite 中当前支持的浏览器版本列表。

通过 CLI 向导安装

你可以在你的机器上的任何地方运行 create astro，所以在开始之前没有必要为你的项目创建一个新的空目录。如果你还没有为你的新项目准备一个空目录，向导会自动帮你创建一个。

在终端中运行以下命令以启动安装向导
- npm
- pnpm
- Yarn
终端窗口
# create a new project with npm npm create astro@latest
终端窗口
# create a new project with pnpm pnpm create astro@latest
终端窗口
# create a new project with yarn yarn create astro
如果一切顺利，你将看到一条成功消息，以及一些推荐的后续步骤。
现在你的项目已经创建好了，你可以使用 cd 命令进入你的新项目目录来开始使用 Astro。
如果你在 CLI 向导中跳过了“安装依赖项？”这一步，那么在继续之前请务必安装你的依赖项。
- npm
- pnpm
- Yarn
终端窗口
npm install
终端窗口
pnpm install
终端窗口
yarn install
你现在可以启动 Astro 开发服务器，并在构建项目时查看实时预览！

CLI 安装标志

你可以使用带有附加标志的 create astro 命令来自定义设置过程（例如，对所有问题回答“是”，跳过 Houston 动画）或你的新项目（例如，是否安装 git，添加集成）。

查看所有可用的 create astro 命令标志

添加集成

你可以通过将 --add 参数传递给 create astro 命令，来启动一个新的 Astro 项目并同时安装任何支持 astro add 命令的官方集成或社区集成。

在终端中运行以下命令，替换为任何支持 astro add 命令的集成

# create a new project with React and Partytown
npm create astro@latest -- --add react --add partytown

# create a new project with React and Partytown
pnpm create astro@latest --add react --add partytown

# create a new project with React and Partytown
yarn create astro --add react --add partytown

使用主题或入门模板

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

在终端中运行以下命令，替换为你想要使用的官方 Astro 入门模板名称，或主题的 GitHub 用户名和仓库

# create a new project with an official example
npm create astro@latest -- --template <example-name>

# create a new project based on a GitHub repository’s main branch
npm create astro@latest -- --template <github-username>/<github-repo>

# create a new project with an official example
pnpm create astro@latest --template <example-name>

# create a new project based on a GitHub repository’s main branch
pnpm create astro@latest --template <github-username>/<github-repo>

# create a new project with an official example
yarn create astro --template <example-name>

# create a new project based on a GitHub repository’s main branch
yarn create astro --template <github-username>/<github-repo>

默认情况下，此命令将使用模板仓库的 main 分支。要使用不同的分支名称，请将其作为 --template 参数的一部分传递：<github-username>/<github-repo>#<branch>。

手动设置

本指南将引导你完成手动安装和配置新 Astro 项目的步骤。

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

创建你的目录

创建一个与项目同名的空目录，然后进入该目录。
终端窗口
```
mkdir my-astro-project
cd my-astro-project
```
进入新目录后，创建项目的 package.json 文件。你将用它来管理项目依赖项，包括 Astro。如果你不熟悉这种文件格式，请运行以下命令来创建一个。
- npm
- pnpm
- Yarn
终端窗口
npm init --yes
终端窗口
pnpm init
终端窗口
yarn init --yes
安装 Astro

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

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

创建你的第一个页面

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

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

---
// Welcome to Astro! Everything between these triple-dash code fences
// is your "component frontmatter". It never runs in the browser.
console.log('This runs in your terminal, not the browser!');
---
<!-- Below is your "component template." It's just HTML, but with
    some magic sprinkled in to help you build great templates. -->
<html>
  <body>
    <h1>Hello, World!</h1>
  </body>
</html>
<style>
  h1 {
    color: orange;
  }
</style>

创建你的第一个静态资源

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

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

在本指南中，将以下代码片段复制并粘贴到你的新文件中
public/robots.txt
```
# Example: Allow all bots to scan and index your site.
# Full syntax: 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.js.cn/config
export default defineConfig({});
```
如果你想在项目中使用如 React、Svelte 等UI 框架组件，或使用 MDX 或 Partytown 等其他工具，你可以在这里手动导入和配置集成。

阅读 Astro 的 API 配置参考以获取更多信息。
添加 TypeScript 支持

TypeScript 是通过 tsconfig.json 进行配置的。即使你不编写 TypeScript 代码，这个文件也很重要，它能让 Astro 和 VS Code 等工具了解你的项目。如果没有 tsconfig.json 文件，编辑器中的某些功能（如 npm 包导入）将无法得到完全支持。

如果你打算编写 TypeScript 代码，建议使用 Astro 的 strict 或 strictest 模板。你可以在 astro/tsconfigs/ 查看和比较这三种模板配置。

在你项目的根目录下创建 tsconfig.json，并将下面的代码复制进去。（你可以为你的 TypeScript 模板使用 base、strict 或 strictest）
tsconfig.json
```
{
  "extends": "astro/tsconfigs/base"
}
```
阅读 Astro 的 TypeScript 设置指南以获取更多信息。
后续步骤

如果你已按照上述步骤操作，你的项目目录现在应该如下所示
- 目录node_modules/
  - …
- 目录public/
  - robots.txt
- 目录src/
  - 目录pages/
    index.astro
- astro.config.mjs
- package-lock.json 或 yarn.lock, pnpm-lock.yaml 等
- package.json
- tsconfig.json
你现在可以启动 Astro 开发服务器，并在构建项目时查看实时预览！

贡献社区赞助