# @ecopages/core 中文文档

规范地址：https://npmcn.com/package/%40ecopages/core/

版本：0\.7\.1
npm 元数据更新时间：2026-11-12T23:43:29.246Z
中文译文更新时间：2026-11-13T06:09:11.950Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40ecopages/core
原文对照：https://npmcn.com/package/%40ecopages/core/?lang=original
源码仓库：https://github.com/ecopages/ecopages

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

- 包体积（解压后）：2.4 MB，737 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^24\.22\.0 \|\| \>=26\.0\.0
- 运行依赖：12 个
- peer 依赖：@ecopages/dev-toolbar 0\.7\.1
- 首次发布：2026-03-08T20:17:53.659Z
- 最新版本发布：2026-11-12T23:43:28.897Z
- 近 30 天下载量：4452（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：126（近 12 个月 126 个）

## 中文简介

Ecopage 核心软件包

## 安装

```sh
npm install @ecopages/core
```

也可以使用：`pnpm add @ecopages/core`、`yarn add @ecopages/core`、`bun add @ecopages/core`

## README

# @ coopages/ core (中文(简体) )

Ecopages框架的基础引擎. 它提供了运行Ecopages应用程序所需的核心构建管道,开发服务器,路由和插件架构.

## 概览

Ecopages是可扩展的静态站点生成器(SSG),运行于节点上. 它默认包含一个严格的MPA(多页应用)架构,在构建时或请求时渲染出HTML,只在必要情况下才给互动岛屿水分.

-   **运行时边界**数字 : `createApp()` 使用节点HTTP主机.
-   **构建所有权**:滚动构建了应用程序.
-   **框架不可知论**:通过官方集成插件对KitaJS,Lit,React,和MDX的一等支持.
-   **广泛**:用自定义处理器或渲染集成来钩入构建过程.

## 建筑

核心如何在内部工作(配置和 `AppRuntime`中,在 [开发者页面](https://npmcn.com/package/apps/docs/src/content/dev),服务于 `/dev` 在文件网站。 开始于 [概览](https://npmcn.com/package/apps/docs/src/content/dev/index.mdx)。 。 。 .

## 安装

```bash
pnpm add @ecopages/core
```

您还可以使用 `npm` 或者说 `yarn`。 。 。 .

## 基本用途

Ecopages架构围绕 `eco.config.ts` 文档和应用程序的入口.

### 1\. 配置(`eco.config.ts`(中文(简体) )

配置您的集成、 处理器和默认元数据 :

```typescript
import { defineConfig } from '@ecopages/core/config';
import { ecopagesJsxPlugin } from '@ecopages/ecopages-jsx';

export default defineConfig({
    baseUrl: 'https://example.com',
    defaultMetadata: {
        title: 'My Ecopages Site',
        description: 'Built with Ecopages',
    },
    integrations: [ecopagesJsxPlugin()],
});
```

### 2\. 申请条目`app.ts`(中文(简体) )

使用 `createApp`自动解析和加载 `eco.config.ts` 从工程根并服务通过节点 HTTP 主机:

```typescript
import { createApp } from '@ecopages/core/create-app';

const app = await createApp();

await app.start();
```

### 3\. 创建页面

使用 `eco.page()` 工厂来定义静态路线。 把这些放在 `src/pages/`数字 :

```tsx
import { eco } from '@ecopages/core';
import { BaseLayout } from '@/layouts/base-layout';

export default eco.page({
    layout: BaseLayout,
    metadata: () => ({
        title: 'Home',
    }),
    render: () => (
        <div>
            <h1>Welcome to Ecopages</h1>
        </div>
    ),
});
```

平面 `.html` 文件在 `src/pages/` 是 HTML 页面,不需要整合 : `src/pages/about.html` 变成 `/about`,内翻 `src/includes/html.*` 或内置的 HTML 模板。 见 [HTML 页面](https://ecopages.app/docs/core/pages#html-pages)。 。 。 .

### 4\. 可再利用组件

一个组件的导入样式表只有在 Page 使用时才被注入,是否有纯函数。 定义组件为 `eco.component()` 当他们也需要脚本时, `modules`,样式表属性,a `integration` 覆盖或由另一个集成器渲染 :

```tsx
import { eco } from '@ecopages/core';

export const MyButton = eco.component({
    dependencies: {
        stylesheets: ['./button.css'],
    },
    render: ({ label }) => <button className="my-button">{label}</button>,
});
```

依赖所有权影响最终资产包装:

-   所声明的样式表和脚本 `eco.html()` 仍为Html所有,可作为共享的全应用资产排放.
-   从 Page 、 布局 或 组件中宣布的样式表和脚本, 将解析为 已实现的路由 .
-   这种分割是故意的. 共享的Html资产可以跨道缓存,而页面自有资产可以改变而不会使全局外壳无效.

### 5\. API 处理器

使用服务器侧路由添加 `defineApiHandler` 或方法帮助者(`defineGet`, (中文(简体) ), `definePost`(中文(简体) ). 登记在你的 `app` 开始前实例 :

```typescript
import { defineApiHandler, defineGet, json } from '@ecopages/core';

export const helloWorld = defineGet({
    path: '/api/hello',
    handler: async ({ response }) => {
        return response.json({ message: 'Hello World' });
    },
});

// Equivalent with an explicit method:
export const helloWorldAlt = defineApiHandler({
    path: '/api/hello',
    method: 'GET',
    handler: async () => json({ message: 'Hello World' }),
});
```

`defineQuery`, (中文(简体) ), `app.query()` 财务报告和审定财务报表 `api.query` 操作 HTTP QUERY 方法(RFC 1008):一个安全、有声读取的,其请求体携带查询。 它需要一个 `schema.body` 喜欢 `definePost`和生态页 添加没有缓冲, `Accept-Query` 或者说 `Vary`; 如果需要, 设置在响应上 。 这里的QUERY是方法,而不是处理上下文 `query` 字段(URL的搜索参数).

分组相关路线 `defineGroupHandler`. 偏爱 `api.get` 编号 : `api.post` 内部的助手 `routes` 回调 :

```typescript
import { defineGroupHandler } from '@ecopages/core';

export const adminGroup = defineGroupHandler({
    prefix: '/admin',
    routes: (api) => [
        api.get({
            path: '/',
            handler: async ({ response }) => response.json({ ok: true }),
        }),
        api.post({
            path: '/items',
            handler: async ({ response }) => response.status(201).json({ created: true }),
        }),
    ],
});
```

独立的响应助手( E)`json`, (中文(简体) ), `html`, (中文(简体) ), `redirect`共享与 `context.response.json()` 编号 : `context.response.html()`。 。 。 .

注册预建的处理器 `app.add()`启用 `app.get(path, handler)` 仅在定义内含路径时 `app.ts`。 。 。 .

方法帮助者也会接受一个不包含 `path`,用于导出端点文件(`*.api.ts`, (中文(简体) ), `.api.tsx`, (中文(简体) ), `.api.js` 或者说 `.api.jsx`),其页面目录下路径给出了URL. 这个 `api.get` 编号 : `api.post` 组帮助仍然需要 `path`,以及 `app.add()` 财务报告和审定财务报表 `app.group()` 扔给一个手无寸铁的人.

同一处理器的文件系统形式是一个端点文件. `src/pages/api/hello.api.ts` 答题 `/api/hello` 没有 `app.add()` 电话 :

```typescript
import { defineGet } from '@ecopages/core';

export const GET = defineGet({
    handler: async ({ response }) => response.json({ message: 'Hello World' }),
});
```

文件的规则(405和405) `Allow`,装入错误, `app.ts` 相同 URL 上的路由) [端点文件文档](https://ecopages.app/docs/server/endpoint-files)\- 内部在 [路线](https://npmcn.com/package/apps/docs/src/content/dev/routing.mdx) 开发者页面. 配置一个端点文件的应用程序的构建会发布服务器捆绑( E)`dist/server/`),释放服务器模块,然后检查每个文件的导出,即使没有其他操作器注册,所以 `ecopages start` 为它服务.

### 6\. 错误页

文件系统 `src/pages/404.*` 财务报告和审定财务报表 `500.*` 优先发言。 对于明确路线的应用程序,请登录该应用程序上的视图:

```typescript
import NotFoundView from './src/views/not-found.kita';
import ServerErrorView from './src/views/server-error.kita';

app.notFound(NotFoundView);
app.serverError(ServerErrorView);
```

导入视图并传递给 `ctx.render`, (中文(简体) ), `ctx.renderPartial`, (中文(简体) ), `app.static()`,或错误的页面帮助。 默认导出集成自有文件成为视图参考: 开发通过应用程序模块加载器加载它, 因此保存重载而不重新启动, 生产读取模块 `ecopages build` 致 `dist/server/`。一个没有默认导出的文件,例如一个命名为平原组件的文件,即导入本身。 一个完全清晰的视图通过与文件系统Page相同的路由管道,包括它的布局,默认元数据,机器人元和页面客户端计划. 传到观景台的道具 `metadata`。 。 。 .

当没有配置自定义页面时,则使用内置的 HTML 默认值.

将处理器附入您的 `app.ts` 条目 :

```typescript
import { createApp } from '@ecopages/core/create-app';
import { helloWorld } from './handlers/hello';

const app = await createApp();

app.add(helloWorld);

await app.start();
```

见 [正式文件](https://ecopages.app/) 高级使用、API处理器和集成.

## 导入结构

使用 `create-app` 用于运行时间启动的子路径和用于标准作者助手的根包 :

```ts
import { createApp } from '@ecopages/core/create-app';
import { defineApiHandler, defineGet, defineGroupHandler, eco } from '@ecopages/core';
```

> \[注\] 使用 `createApp()` 从 `@ecopages/core/create-app` 作为应用程序的切入点.

## 输入点角色

已出版的子路径按建筑角色而不是源文件夹分类.

### 应用程序作者

当创建 Ecopage 应用程序时使用这些切入点 :

-   `@ecopages/core`
-   `@ecopages/core/create-app`
-   `@ecopages/core/config`
-   `@ecopages/core/errors`
-   `@ecopages/core/declarations` (仅类型;还申报副作用CSS进口,因此不按项目申报而输入)
-   `@ecopages/core/env` (仅类型)

### 整合作者

使用 `@ecopages/core/integration` 为融合合同、提供钩子和共享融合运行时间帮助者.

### 处理器作者

使用 `@ecopages/core/processor` 用于处理器合同和生成资产辅助器。 样式表处理器运行大小写 `stylesheetProcessorContract` 从 `@ecopages/core/processor/contract` 在测试中.

### 构建扩展

使用 `@ecopages/core/build` 用于构建适配器和插件。 使用 `@ecopages/core/build/contracts` 用于稳定构建的合同,在浏览器中也需要安全构建图表.

### 浏览器运行时扩展

使用 `@ecopages/core/client` 用于浏览器导航和客户端运行时间帮助.

### 运行时丢失条目

`@ecopages/core/config/write-types`, (中文(简体) ), `@ecopages/core/hmr/client/hmr-runtime`,以及 `@ecopages/core/view-reference` 继续导出, 因为 Ecopages 在运行时按路径加载它们 。 它们是执行条目,而不是一般的作者表。 App作者导入视图文件,而不是此子路径 .

`@ecopages/core/errors` 仍然是根错误导出的一个别名.

## 常见问题

### @ecopages/core 是什么？

Ecopage 核心软件包

### 如何安装 @ecopages/core？

在项目目录运行 npm install @ecopages/core，或使用 pnpm add / yarn add / bun add。

### @ecopages/core 支持 TypeScript 吗？

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

### @ecopages/core 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @ecopages/core 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^24\.22\.0 \|\| \>=26\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @ecopages/core 可以商用吗？

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

### @ecopages/core 的下载量有多少？

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

### @ecopages/core 还在维护吗？

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