import { Tabs, TabItem, FileTree, CardGrid, LinkCard, Steps } from '@astrojs/starlight/components'; import PackageManagerTabs from '/components/tabs/PackageManagerTabs.astro'; import ReadMore from '/components/ReadMore.astro';

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

你还可以运行带有 template 标志的 CLI 命令，以使用任何现有主题或起始模板来开始你的项目。探索我们的 主题和起始模板 showcase，你可以在其中浏览到博客、作品集、文档网站、落地页等主题！

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

:::tip[在线预览] 想在浏览器中尝试 Astro 吗？访问 astro.new 浏览我们的起始模板，并在不离开浏览器的情况下启动一个新的 Astro 项目。 :::

前提条件

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

浏览器兼容性

Astro 使用 Vite 构建，Vite 默认针对支持现代 JavaScript 的浏览器。要阅读完整的参考，你可以 在 Vite 中查看当前支持的浏览器版本列表。

通过 CLI 向导安装

你可以在计算机上的任何地方运行 create astro，因此在开始之前无需创建一个新的空目录。如果你还没有为你的新项目准备一个空目录，向导将会自动为你创建一个。

<PackageManagerTabs> <Fragment slot="npm"> ```shell # 使用 npm 创建一个新项目 npm create astro@latest ``` </Fragment> <Fragment slot="pnpm"> ```shell # 使用 pnpm 创建一个新项目 pnpm create astro@latest ``` </Fragment> <Fragment slot="yarn"> ```shell # 使用 yarn 创建一个新项目 yarn create astro ``` </Fragment> </PackageManagerTabs> 如果一切顺利，你将看到一个成功信息，随后是一些推荐的后续步骤。

2. 现在你的项目已经创建好了，你可以 cd 进入你的新项目目录开始使用 Astro。

  1. 如果你在 CLI 向导中跳过了 "Install dependencies?"（安装依赖？） 步骤，那么在继续之前请确保安装你的依赖。

  2. 现在你可以 启动 Astro 开发服务器 并在构建时看到你的项目的实时预览！

CLI 安装标志

你可以运行带有附加标志的 create astro 命令来自定义安装的过程（例如，对每次询问都统一回答“是”，跳过 Houston 动画）或你的新项目（例如，是否安装 git，添加集成）。

请参阅所有可用的 create astro 命令标志

添加集成

你可以通过向 create astro 命令传递 --add 参数，它会在开始一个新的 Astro 项目的同时，为其安装任何支持 astro add 命令的 官方集成 或社区集成。

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

使用主题或起始模板

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

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

基于 GitHub 仓库的 main 分支创建一个新项目

npm create astro@latest -- --template /

</Fragment> <Fragment slot="pnpm"> ```shell # 使用官方示例创建一个新项目 pnpm create astro@latest --template <example-name> # 基于 GitHub 仓库的 main 分支创建一个新项目 pnpm create astro@latest --template <github-username>/<github-repo>

基于 GitHub 仓库的 main 分支创建一个新项目

yarn create astro --template /

</Fragment> </PackageManagerTabs> 默认情况下，此命令将使用模板仓库的 `main` 分支。如果要使用不同的分支名称，请在 `--template` 参数中指定：`<github-username>/<github-repo>#<branch>`。 ## 手动安装 本指南将指导你手动安装和配置新的 Astro 项目。 如果你不想使用我们的自动 `create astro` CLI 工具，可以按照下面的指南自行设置你的项目。 <Steps> 1. 创建你的目录 创建一个以你的项目命名的空目录，然后进入该目录。 ```bash mkdir my-astro-project cd my-astro-project ``` 进入你的新目录后，创建你的项目 `package.json` 文件。这是你管理项目依赖项（包括 Astro）的方式。如果你不熟悉这种文件格式，请运行以下命令创建一个。 <PackageManagerTabs> <Fragment slot="npm"> ```shell npm init --yes ``` </Fragment> <Fragment slot="pnpm"> ```shell pnpm init ``` </Fragment> <Fragment slot="yarn"> ```shell yarn init --yes ``` </Fragment> </PackageManagerTabs> 2. 安装 Astro 首先，在你的项目中安装 Astro 的依赖项。 :::note[重要] Astro 必须安装在本地，不能全局安装。确保你没有运行 `npm install -g astro`、`pnpm add -g astro` 或 `yarn add global astro`。 ::: <PackageManagerTabs> <Fragment slot="npm"> ```shell npm install astro ``` </Fragment> <Fragment slot="pnpm"> ```shell pnpm add astro ``` </Fragment> <Fragment slot="yarn"> ```shell yarn add astro ``` </Fragment> </PackageManagerTabs> 然后，用以下内容替换你的 `package.json` 中的任何占位符 "scripts" 部分： ```json title="package.json" del={3} ins={4-6} { "scripts": { "test": "echo \"Error: no test specified\" && exit 1", "dev": "astro dev", "build": "astro build", "preview": "astro preview" }, } ``` 你将在本指南后面使用这些脚本来启动 Astro 并运行其不同的命令。 3. 创建你的第一个页面 在你的文本编辑器中，在你的目录下的 `src/pages/index.astro` 创建一个新文件。这将是你项目中的第一个 Astro 页面。 对于本指南，请将以下代码片段（包括 `---` 破折号）复制并粘贴到你的新文件中： ```astro title="src/pages/index.astro" --- // 欢迎使用 Astro！这些三破折号代码围栏之间的内容是你的 "component frontmatter"。它不会在浏览器中运行。 console.log('这段代码在你的终端运行，而不是在浏览器中！'); --- <!-- 下面是你的 "component template"。它只是 HTML，但加入了一些魔法，帮助你构建出色的模板。 --> <html> <body> <h1>Hello, World!</h1> </body> </html> <style> h1 { color: orange; } </style> ``` 4. 创建你的第一个静态资源 你还需要创建一个 `public/` 目录来存储你的静态资源。Astro 将始终在你的最终构建中包含这些资源，因此你可以安全地从你的组件模板中引用它们。 在你的文本编辑器中，在你的目录下的 `public/robots.txt` 创建一个新文件。`robots.txt` 是大多数网站会包含的一个简单文件，用于告诉像 Google 这样的搜索机器人如何处理你的网站。 对于本指南，请将以下代码片段复制并粘贴到你的新文件中： ```diff title="public/robots.txt" # 示例：允许所有机器人扫描并索引你的网站。 # 完整语法：https://developers.google.com/search/docs/advanced/robots/create-robots-txt User-agent: * Allow: / ``` 5. 创建 `astro.config.mjs` Astro 使用 `astro.config.mjs` 进行配置。如果你不需要配置 Astro，这个文件是可选的，但你现在可能希望创建它。 在你项目的根目录下创建 `astro.config.mjs`，并将下面的代码复制到其中： ```js title="astro.config.mjs" import { defineConfig } from 'astro/config'; // https://astro.build/config export default defineConfig({}); ``` 如果你想在你的项目中包含 [UI 框架组件](/zh-cn/guides/framework-components/)，如 React、Svelte 等，或使用其他工具，如 MDX 或 Partytown，这里是你[手动导入和配置集成](/zh-cn/guides/integrations-guide/)的地方。 阅读 Astro 的 [API 配置参考](/zh-cn/reference/configuration-reference/) 以获取更多信息。 6. 添加 TypeScript 支持 TypeScript 使用 `tsconfig.json` 进行配置。即使你不编写 TypeScript 代码，这个文件也很重要，以便工具（如 Astro 和 VS Code）了解你的项目。某些功能（如 npm 包导入）在没有 `tsconfig.json` 文件的情况下在编辑器中不完全支持。 如果你打算编写 TypeScript 代码，建议使用 Astro 的 `strict` 或 `strictest` 模板。你可以在 [astro/tsconfigs/](https://github.com/withastro/astro/blob/main/packages/astro/tsconfigs/) 查看并比较三种模板配置。 在你项目的根目录下创建 `tsconfig.json`，并将下面的代码复制到其中。（你可以使用 `base`、`strict` 或 `strictest` 作为你的 TypeScript 模板）： ```json title="tsconfig.json" "base" { "extends": "astro/tsconfigs/base" } ``` 阅读 Astro 的 [TypeScript 设置指南](/zh-cn/guides/typescript/#设置) 以获取更多信息。 7. 接下来 如果你已经按照上面的步骤操作，你的项目目录现在应该如下所示： <FileTree> - node_modules/ - public/ - robots.txt - src/ - pages/ - index.astro - astro.config.mjs - package-lock.json 或 `yarn.lock`、`pnpm-lock.yaml` 等。 - package.json - tsconfig.json </FileTree> 8. 现在你可以[启动 Astro 开发服务器](/zh-cn/develop-and-build/#启动-astro-开发服务器) 并在构建项目的同时查看实时预览了！ </Steps>
开始使用
开发和构建