# @geekvetica/nx-astro 中文文档

规范地址：https://npmcn.com/package/%40geekvetica/nx-astro/

版本：3\.0\.4
npm 元数据更新时间：2026-11-09T13:35:47.065Z
中文译文更新时间：2026-11-16T01:55:17.521Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40geekvetica/nx-astro
原文对照：https://npmcn.com/package/%40geekvetica/nx-astro/?lang=original
项目主页：https://github.com/geekvetica/nx-astro#readme
源码仓库：https://github.com/Geekvetica/nx-astro

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：396 kB，186 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：nx \>=22\.0\.0 \<24\.0\.0，astro \>=5\.0\.0 \<8\.0\.0
- 首次发布：2025-10-14T20:39:48.174Z
- 最新版本发布：2026-11-09T13:35:46.761Z
- 近 30 天下载量：4996（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 6 个）

## 中文简介

Astro 的 Nx 插件, 用于为 Nx monrepos 中的 Astro 应用程序提供无缝集成的生成器和执行器

## 安装

```sh
npm install @geekvetica/nx-astro
```

也可以使用：`pnpm add @geekvetica/nx-astro`、`yarn add @geekvetica/nx-astro`、`bun add @geekvetica/nx-astro`

## README

# nx- 天体

> Astro 的 Nx 插件 - 用 Nx 单列波创建 Astro 快速网站

[![npm version](https://img.shields.io/npm/v/@geekvetica/nx-astro)](https://www.npmjs.com/package/@geekvetica/nx-astro) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 特征

-   **自动任务推论** - 检测Astro项目并自动配置任务
-   **代码生成器** - 容易操作的脚手架应用程序和部件
-   **完整类型脚本支持** - 类型安全配置和发展
-   **Nx 缓存** - 闪电快车用智能快车建造
-   **内容集** - 对Astro内容集的一等支持
-   **安保部门支助** - 建立静态网站或服务器应用程序
-   **测试集成** - 为单位和综合测试提供内建测试支助

## 快速启动

### 安装

```bash
# Create a new Nx workspace
npx create-nx-workspace@latest my-workspace

# Install nx-astro
cd my-workspace
npm install --save-dev @geekvetica/nx-astro

# Initialize the plugin
nx g @geekvetica/nx-astro:init
```

### 创建您的第一个应用程序

```bash
# Generate an Astro application
nx g @geekvetica/nx-astro:application my-app

# Start development server
nx dev my-app

# Build for production
nx build my-app
```

### 创建组件

```bash
# Generate a component
nx g @geekvetica/nx-astro:component Button --project=my-app

# Generate a component in a subdirectory
nx g @geekvetica/nx-astro:component Card --project=my-app --directory=ui
```

## 可用命令

一旦您在工作空间中有Astro应用程序,您就可以运行这些命令:

```bash
# Development
nx dev my-app              # Start dev server with HMR
nx dev my-app --port=3000  # Custom port

# Building
nx build my-app            # Production build
nx build my-app --verbose  # Verbose output

# Preview
nx preview my-app          # Preview production build

# Type Checking
nx check my-app            # Run type checking
nx check my-app --watch    # Watch mode

# Testing
nx test my-app             # Run tests
nx test my-app --coverage  # With coverage

# Content Collections
nx sync my-app             # Generate content types
```

## Monorepo 工作流程

该插件与 Nx 单列波 特性无缝融合 :

```bash
# Run tasks for multiple projects
nx run-many --target=build --projects=app1,app2,app3

# Build all projects
nx run-many --target=build --all

# Build only affected projects (based on git changes)
nx affected --target=build

# View project graph
nx graph
```

## 模板

创建应用程序时从启动模板中选择 :

-   **最小** - 基本启动文件
-   **博客** - 有内容收藏的博客模板
-   **组合** - 展示项目的组合模板

```bash
nx g @geekvetica/nx-astro:application my-blog --template=blog
nx g @geekvetica/nx-astro:application my-portfolio --template=portfolio
```

## 导入已存在的项目

将已有的 Astro 项目移入您的 Nx 工作空间 `import` 生成器 :

```bash
# Import from a local path
nx g @geekvetica/nx-astro:import --source=../my-astro-app

# Import with custom name and directory
nx g @geekvetica/nx-astro:import --source=./external/astro-site --name=my-site --directory=apps/websites

# Import with tags for organization
nx g @geekvetica/nx-astro:import --source=/path/to/app --tags=astro,web,public-facing

# Import with custom TypeScript path alias
nx g @geekvetica/nx-astro:import --source=../app --name=my-app --importPath=@myorg/my-app
```

导入生成器自动 :

-   验证源是一个有效的 Astro 项目
-   复制所有工程文件(不包括节点-模块、构建输出等)
-   创建 包含所有标准目标的 Nx 项目配置( dev, 构建, 预览, 检查, 同步)
-   更新 tsconfig.base.json 中的 TypeScript 路径映射
-   在工作区注册工程

导入后 :

```bash
# Install dependencies
pnpm install

# Start development
nx dev my-site

# Build for production
nx build my-site
```

## 配置

### 插件配置

配置插件在 `nx.json`数字 :

```json
{
  "plugins": [
    {
      "plugin": "@geekvetica/nx-astro",
      "options": {
        "devTargetName": "dev",
        "buildTargetName": "build",
        "checkTargetName": "check"
      }
    }
  ]
}
```

### 项目配置

插件自动推断任务 `astro.config.mjs`。要自定义,请创建 `project.json`数字 :

```json
{
  "name": "my-app",
  "targets": {
    "dev": {
      "executor": "@geekvetica/nx-astro:dev",
      "options": {
        "port": 3000,
        "host": true
      }
    },
    "build": {
      "executor": "@geekvetica/nx-astro:build",
      "options": {
        "outputPath": "dist/apps/my-app",
        "site": "https://example.com"
      }
    }
  }
}
```

## 共享图书馆

创建共享组件库, 供多个 Astro 应用程序使用 :

```bash
# Create shared library
nx g @nx/js:library shared-ui --directory=libs/shared-ui

# Configure path aliases in tsconfig.base.json
{
  "compilerOptions": {
    "paths": {
      "@my-org/shared-ui/*": ["libs/shared-ui/src/*"]
    }
  }
}

# Use in any Astro app
import Button from '@my-org/shared-ui/components/Button.astro';
```

## 内容集

完全支持带有类型生成的 Astro 内容收藏 :

```typescript
// src/content/config.ts
import { defineCollection, z } from 'astro:content';

const blog = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    pubDate: z.date(),
    description: z.string(),
  }),
});

export const collections = { blog };
```

```bash
# Generate types
nx sync my-app

# Types are now available
import { getCollection } from 'astro:content';
const posts = await getCollection('blog'); // Fully typed!
```

## 安保部门支助

构建服务器任务应用程序 :

```javascript
// astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

export default defineConfig({
  output: 'server',
  adapter: node({ mode: 'standalone' }),
});
```

```bash
nx build my-app
node dist/apps/my-app/server/entry.mjs
```

## 测试

插件包括用于测试的 Vitest 配置 :

```typescript
// src/components/Button.test.ts
import { experimental_AstroContainer as AstroContainer } from 'astro/container';
import Button from './Button.astro';

test('renders button', async () => {
  const container = await AstroContainer.create();
  const result = await container.renderToString(Button, {
    slots: { default: 'Click me' },
  });
  expect(result).toContain('Click me');
});
```

```bash
nx test my-app
nx test my-app --coverage
nx test my-app --watch
```

## 业绩

Nx 缓存会大大地改进构建时间 :

```bash
# First build (cold)
nx build my-app
# ✓ Built in 15.3s

# Second build (cached)
nx build my-app
# ✓ Nx read the output from the cache (0.2s)
```

## CI/CD 一体化

优化您的 CI 管道与受影响的检测:

```yaml
# .github/workflows/ci.yml
- name: Build affected projects
  run: nx affected --target=build --base=origin/main

- name: Test affected projects
  run: nx affected --target=test --base=origin/main
```

## 文档

### 指南

-   **[发电机指南](https://npmcn.com/package/%40geekvetica/docs/generators.md)** - 创建项目和组成部分
-   **[执行者指南](https://npmcn.com/package/%40geekvetica/docs/executors.md)** - 运行dev服务器、构建和测试
-   **[配置指南](https://npmcn.com/package/%40geekvetica/docs/configuration.md)** - 配置插件和工程
-   **[移徙指南](https://npmcn.com/package/%40geekvetica/docs/migration-guide.md)** - 迁移现有的Astro项目
-   **[实例](https://npmcn.com/package/%40geekvetica/docs/examples.md)** - 实际世界使用实例

### 参考文献

-   **[API 参考](https://npmcn.com/package/%40geekvetica/docs/api-reference.md)** - 完整的计划和类型
-   **[财务问题](https://npmcn.com/package/%40geekvetica/docs/faq.md)** - 经常问的问题
-   **[解决问题](https://npmcn.com/package/%40geekvetica/docs/troubleshooting.md)** - 共同问题和解决办法

### 设置

-   **[CI/CD 设置指南](https://npmcn.com/package/%40geekvetica/docs/ci-cd-setup.md)** - 配置连续集成
-   **[E2E 测试指南](https://npmcn.com/package/%40geekvetica/docs/e2e-testing-guide.md)** - 端到端测试设置
-   **[建筑](https://npmcn.com/package/%40geekvetica/docs/architecture.md)** - 技术架构概览

## 所需资源

-   **无**: 21.6.4或以上
-   **天体**: 5.x, 6.x, 或 7.x
-   **节点.js**:22.12.0或更高(所有支持的Astro版本的全项目最低标准)
-   **类型脚本**: 5.9.x或 6.x (中文(简体) )`astro check` 尚不支持类型Script 7)

Astro 5.x和 6.x仍然被这个插件所支持,但它们使用相同的节点.js 22.12.0+基线作为Astro 7.x.

## 版本支持

| nx- 天体 | 天体 | 节点.js | 状态 |
| --- | --- | --- | --- |
| 1.x 运算 | 5.x 电话 | 第22.12.0号决定 | 活动 |
| 1.x 运算 | 6.x (单位:千美元) | 第22.12.0号决定 | 活动 |
| 2.x 数据 | 5.x 电话 | 第22.12.0号决定 | 活动 |
| 2.x 数据 | 6.x (单位:千美元) | 第22.12.0号决定 | 活动 |
| 2.x 数据 | 7.x 电话 | 第22.12.0号决定 | 活动 |

### Astro 版本选择

在初始化插件时, 您可以指定要安装的 Astro 格式 :

```bash
# Install with Astro 7.x (default)
nx g @geekvetica/nx-astro:init

# Install with Astro 7.x explicitly
nx g @geekvetica/nx-astro:init --astro-version=7

# Install with Astro 6.x
nx g @geekvetica/nx-astro:init --astro-version=6

# Install with Astro 5.x
nx g @geekvetica/nx-astro:init --astro-version=5
```

该插件会自动检测到现有的Astro安装并使用该版本范围.

注意:无论Astro主版本选择如何,此插件都需要22.12.0或更高.

### 从Astro 6 迁移到Astro 7

如果您有使用 Astro 6 的现有项目, 并且想要升级到 Astro 7 :

1.  更新您的工作空间依赖性 :
    
    ```bash
    pnpm add -D astro@^7.3.6 @astrojs/node@^11.1.7
    ```
    
    更新任何其他 `@astrojs/*` 与Astro 7的相容主机融合.
    
2.  节点.js要求不变(22.12.0+)
    
3.  Astro 7 键断键变化 :
    
    -   Vite 8( 请检查Vite 插件兼容性)
    -   基于 Rust 的编译器取代了 Go 编译器,并对无效的 HTML 更为严格(例如现在的未关闭标记出错). 删除 `experimental.rustCompiler` 如果设置.
    -   `compressHTML` 默认为 `'jsx'`设置 `compressHTML: true` 以保留先前的 HTML 意识白空间处理.
    -   Markdown默认由Sätteri提供. 要保留备注/恢复插件, 安装 `@astrojs/markdown-remark` 设置 `markdown.processor: unified()`。 。 。 .
    -   高级路由稳定并使用 `src/fetch.ts` 作为它的入门点。 移动 `experimental.advancedRouting.fetchFile` 到顶层 `fetchFile` 选项(或设置) `fetchFile: null` 以禁用).
    -   `@astrojs/db` 编辑 `astro db` 编号 : `astro login` 编号 : `astro link` CLI 命令被删除.
    -   折旧 `astro:transitions` 帮助者( e)`TRANSITION_*` 常数, `isTransition*Event()`, (中文(简体) ), `createAnimationScope()`页:1.
4.  `astro dev` 当检测到AI编码代理时, 现在解入背景 。 Nx -Astro号 `dev` 执行器将服务器保存在前景( 它设置) `ASTRO_DEV_BACKGROUND=0`所以Nx可以监督它。 设定 `ASTRO_DEV_BACKGROUND=1` 自己选择回去.
    

### 从Astro 5搬到Astro 6

如果您有使用 Astro 5 的现有项目,并想要升级到 Astro 6 :

1.  更新您的工作空间依赖性 :
    
    ```bash
    pnpm add -D astro@^6.2.0 @astrojs/node@^10.0.0
    ```
    
2.  确保节点.js版本为22.12.0或更高
    
3.  更新内容集以使用内容层 API( 遗产集在 Astro 6 中被删除)
    
4.  如果您需要迁移帮助, 请启用您的遗留兼容旗 `astro.config.mjs`数字 :
    
    ```js
    export default defineConfig({
      legacy: {
        collectionsBackwardsCompat: true,
      },
    });
    ```
    
5.  Astro 6 中键断切变化 :
    
    -   节点18/20支持下降(需要22.12.0+)
    -   Vite 7.0 (检查Vite插件兼容性)
    -   Zod 4.0 (如果使用自定义验证, 更新内容计划)
    -   `Astro.glob()` 删除( 使用 `import.meta.glob()` 改为)
    -   CJS 配置文件已删除( 使用) `.mjs` 或者说 `.ts`(中文(简体) )
    -   遗留内容收藏已删除( 复制到内容层 API)

## 发电机

| 发电机 | 说明 |
| --- | --- |
| `init` | 初始化 nx- astro 插件 |
| `application` | 从模板创建新的 Astro 应用程序 |
| `import` | 将已有的 Astro 项目导入工作空间 |
| `component` | 生成 Astro 组件 |

## 执行者

| 执行者 | 说明 |
| --- | --- |
| `dev` | 用 HMR 运行开发服务器 |
| `build` | 生产建筑 |
| `preview` | 预览制作建筑 |
| `check` | 运行类型脚本类型检查 |
| `test` | 运行虚拟测试 |
| `sync` | 生成内容收藏类型 |

## 实例

### 多站点的 Monorepo

```
my-workspace/
├── apps/
│   ├── marketing/      # Main website
│   ├── blog/           # Company blog
│   └── docs/           # Documentation
└── libs/
    └── shared-ui/      # Shared components
```

```bash
# Build all sites
nx run-many --target=build --all

# Run dev servers with different ports
nx dev marketing  # port 4321
nx dev blog       # port 4322
nx dev docs       # port 4323
```

### 内容收藏博客

```bash
# Create blog
nx g @geekvetica/nx-astro:application my-blog --template=blog

# Generate types for content
nx sync my-blog

# Add posts to src/content/blog/
# Types are automatically updated
```

### 共享组件库

```bash
# Create library
nx g @nx/js:library shared-ui

# Add components
# libs/shared-ui/src/components/Button.astro
# libs/shared-ui/src/components/Card.astro

# Use in apps
import { Button, Card } from '@my-org/shared-ui';
```

## 社区

-   **GitHub 图像**数字 : [报告问题](https://github.com/geekvetica/nx-astro/issues)
-   **讨论情况**数字 : [提问](https://github.com/geekvetica/nx-astro/discussions)
-   **Nx社区**数字 : [加入磁盘](https://discord.gg/nx)
-   **Astro社区**数字 : [加入磁盘](https://astro.build/chat)

## 捐款

欢迎捐款! 见 [捐款额](https://npmcn.com/package/%40geekvetica/CONTRIBUTING.md) 准则.

## 许可证

麻省理工学院

* * *

## 支助

有问题吗? 检查 [解决问题指南](https://npmcn.com/package/%40geekvetica/docs/troubleshooting.md) 或者说 [打开一个问题](https://github.com/geekvetica/nx-astro/issues)。 。 。 .

## 更改日志

见 [释放](https://github.com/geekvetica/nx-astro/releases) 用于版本历史.

## 常见问题

### @geekvetica/nx-astro 是什么？

Astro 的 Nx 插件, 用于为 Nx monrepos 中的 Astro 应用程序提供无缝集成的生成器和执行器

### 如何安装 @geekvetica/nx-astro？

在项目目录运行 npm install @geekvetica/nx-astro，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：nx（\>=22\.0\.0 \<24\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @geekvetica/nx-astro 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @geekvetica/nx-astro 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @geekvetica/nx-astro 可以商用吗？

@geekvetica/nx-astro 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @geekvetica/nx-astro 的下载量有多少？

根据 npm 官方下载统计，@geekvetica/nx-astro 在 2026/10/16 – 2026/11/14 这 30 天内被下载 4,996 次，日均约 167 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @geekvetica/nx-astro 还在维护吗？

最新版本 3\.0\.4 发布于 2026/11/09（6 天前）；至今共发布 18 个版本，其中过去 12 个月发布了 6 个；首次发布于 2025/10/15。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

