跳转到内容

手动安装 Astro

如果你不想使用自动化 CLI 工具,本指南将引导你完成手动安装和配置新 Astro 项目的步骤。

喜欢更快的入门方式?

尝试 create astro CLI 向导 →

前提准备

  • Node.js - v18.14.1 或更高版本。
  • 文本编辑器 - 我们建议使用安装有 Astro 官方扩展VS Code
  • 终端(Terminal) - Astro 可以通过其命令行界面 (CLI) 访问。

安装

如果你不打算使用 create astro 命令工具来自动化创建项目,你可以根据以下说明来自行设置你的项目。

1. 创建项目目录

创建一个空目录,目录名称是你打算使用的项目名称,并导航到该目录。

Terminal window
mkdir my-astro-project
cd my-astro-project

在该目录内,创建 package.json 文件,该文件将管理你的项目依赖,包括 Astro,如果你不熟悉这种文件格式,可以运行下面的命令来直接创建一个。

Terminal window
npm init --yes

2. 安装 Astro

首先,需要在你的项目目录内安装 Astro 的项目依赖。

Terminal window
npm install 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 项目。

3. 创建第一个页面

打开你的编辑器,在 src/pages/ 目录下创建一个新文件 index.astro,这将会是你的第一个页面。

复制并粘贴以下内容到该页面 index.astro 内(包含 --- 内的内容)。

---
// 欢迎来到 Astro!这些三横线所围住的代码
// 就是你的“组件 frontmatter”。它不会运行在浏览器中。
console.log('它运行在终端而非浏览器!');
---
<!-- 下面是你的“组件模板”。 这仅仅是 HTML,但是
带有魔法点缀可以帮助构建更棒的模板。 -->
<html>
<body>
<h1>Hello, World!</h1>
</body>
</html>
<style>
h1 {
color: orange;
}
</style>

4. 创建静态文件

同样,你可以创建一个 public/ 目录来存储你的静态文件。Astro 会在最后的编译中包含进这些文件,以便你可以在你的组件模板内安全地引用他们。

用编辑器在 public/ 目录下创建一个 robots.txt 的文件,该文件将会告诉类似 Google 这样的搜索引擎怎样去对待该站点。

针对该教程,复制并粘贴以下内容至 robots.txt 内:

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.config.mjs 文件,并复制粘贴下面的内容至该文件内:

astro.config.mjs
import { defineConfig } from 'astro/config';
// https://astro.build/config
export default defineConfig({});

如果你想集成像 React、Svelte 这样的UI 框架组件或是使用其他类似 Tailwind 或 Partytown 这样的工具,你可以在手动导入并配置集成章节内获取更多信息。

📚 阅 读Astro 的API配置参考章节可以获得更多内容。

6. 添加 TypeScript 支持

TypeScript 使用tsconfig.json进行配置。即使你不编写 TypeScript 代码,这个文件也很重要,因为 Astro 和 VS Code 等工具知道如何理解你的项目。 如果没有 tsconfig.json 文件,编辑器将不完全支持某些功能(如 npm 包导入)。

如果你打算编写 TypeScript 代码,建议使用 Astro 的strictstrictest的模板。 你可以在 astro/tsconfigs/ 查看和比较三个模板配置。

在项目的根目录创建 tsconfig.json,并将下面的代码复制到其中。(你可以为 TypeScript 模板使用 basestrictstrictest):

tsconfig.json
{
"extends": "astro/tsconfigs/base"
}

最后,创建src/env.d.ts让 TypeScript 知道 Astro 项目中可用的环境类型:

src/env.d.ts
/// <reference types="astro/client" />

📚 阅读 Astro 的 TypeScript 设置指南以获取更多信息。

7. 接下来

如果你按上述一步步操作,你的项目目录应该看上去像是这样:

  • 目录node_modules/
  • 目录public/
    • robots.txt
  • 目录src/
    • 目录pages/
      • index.astro
    • env.d.ts
  • astro.config.mjs
  • package-lock.json 或者 yarn.lockpnpm-lock.yaml,等等。
  • package.json
  • tsconfig.json

祝贺你,你现在可以使用 Astro 了!

如果你完成了这个指南的全部内容,你可以跳转至步骤 2:启动 Astro继续并学习如何首次运行 Astro。