# @finsweet/docs-theme 中文文档

规范地址：https://npmcn.com/package/%40finsweet/docs-theme/

版本：0\.1\.8
npm 元数据更新时间：2025-12-29T15:48:11.516Z
中文译文更新时间：2026-11-14T19:41:00.949Z
软件包许可：ISC

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

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

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

- 包体积（解压后）：20.1 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- peer 依赖：vue ^3\.2\.47，vitepress ^1\.0\.0-alpha\.49
- 首次发布：2023-02-23T14:33:04.584Z
- 最新版本发布：2023-03-14T11:57:42.200Z
- 近 30 天下载量：2846（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 0 个）

## 中文简介

Finsweet 项目的官方docs启动模板.

## 安装

```sh
npm install @finsweet/docs-theme
```

也可以使用：`pnpm add @finsweet/docs-theme`、`yarn add @finsweet/docs-theme`、`bun add @finsweet/docs-theme`

## README

# Finsweet 开发者启动程序

两个客户端 & Power 项目的启动模板 .

在开始使用本模板之前,请花费一些时间阅读文档.

## 参考文献

-   [包含的工具](https://npmcn.com/package/%40finsweet/docs-theme/#readme-included-tools)
-   [所需资源](https://npmcn.com/package/%40finsweet/docs-theme/#readme-requirements)
-   [开始](https://npmcn.com/package/%40finsweet/docs-theme/#readme-getting-started)
    -   [安装](https://npmcn.com/package/%40finsweet/docs-theme/#readme-installing)
    -   [大楼](https://npmcn.com/package/%40finsweet/docs-theme/#readme-building)
        -   [保存关于开发模式的文件](https://npmcn.com/package/%40finsweet/docs-theme/#readme-serving-files-on-development-mode)
        -   [构建多个文件](https://npmcn.com/package/%40finsweet/docs-theme/#readme-building-multiple-files)
        -   [设置路径别名](https://npmcn.com/package/%40finsweet/docs-theme/#readme-setting-up-a-path-alias)
-   [贡献指南](https://npmcn.com/package/%40finsweet/docs-theme/#readme-contributing-guide)
-   [预定义脚本](https://npmcn.com/package/%40finsweet/docs-theme/#readme-pre-defined-scripts)
-   [排雷中心/发改委](https://npmcn.com/package/%40finsweet/docs-theme/#readme-cicd)
    -   [持续整合](https://npmcn.com/package/%40finsweet/docs-theme/#readme-continuous-integration)
    -   [持续部署](https://npmcn.com/package/%40finsweet/docs-theme/#readme-continuous-deployment)
    -   [如何自动向 npm 部署更新](https://npmcn.com/package/%40finsweet/docs-theme/#readme-how-to-automatically-deploy-updates-to-npm)

## 包含的工具

此模板包含一些预配置开发工具:

-   [字体](https://www.typescriptlang.org/): Javascript的上集,增加了多一层打字,为写出代码带来了更多的安全和效率.
-   [高级](https://prettier.io/):代码格式化,保证了Finsweet所有项目的一致性.
-   [ESLint 语录](https://eslint.org/): 执行行业最佳做法的守则。 用这个 [我们自己的自定义配置](https://github.com/finsweet/eslint-config) 保持所有Finsweet项目的一致性.
-   [剧作家](https://playwright.dev/):快速可靠的端到端测试.
-   [兴建](https://esbuild.github.io/): Javascript 捆绑器,用于编译,捆绑并修改原始Typescript文件.
-   [更改](https://github.com/changesets/changesets): 管理您的版本和更改日志的方法 .
-   [Finsweet 类型脚本 Utils](https://github.com/finsweet/ts-utils): 一些帮助您开发 Webflow 的公用事业.

## 所需资源

此模板需要使用 [小时](https://pnpm.js.org/en/)。 您可以 [安装 pnpm](https://pnpm.io/installation) 改为:

```bash
npm i -g pnpm
```

若要自动部署到 npm,请阅读 [持续部署](https://npmcn.com/package/%40finsweet/docs-theme/#readme-continuous-deployment) 节.

## 开始

启动新项目最快的方法是 [从此模板创建新寄存器](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-from-a-template#creating-a-repository-from-a-template)。 。 。 .

一旦新寄存器创建,请更新 `package.json` 带有正确信息的文件,特别是必须独一无二的软件包名称.

### 安装

在创建了新的寄存器后,在您的终端中打开并运行来安装软件包:

```bash
pnpm install
```

如果这是第一次使用 Playwright 而您想要在这个项目中使用它, 您也必须通过运行来安装浏览器 :

```bash
pnpm playwright install
```

您可以阅读更多关于 Playwright 在 [测试](https://npmcn.com/package/%40finsweet/docs-theme/#readme-testing) 节.

还建议您在 VSCode 编辑器中安装以下扩展:

-   [Pretier - 物质代码](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
-   [ESLint 语录](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)

### 大楼

要构建文件, 您有两个定义的脚本 :

-   `pnpm dev`: 构建并创建一个服务于所有文件的本地服务器( 请检查 [保存关于开发模式的文件](https://npmcn.com/package/%40finsweet/docs-theme/#readme-serving-files-on-development-mode) 以获得更多信息.
-   `pnpm build`: 构建到生产目录上 (`dist`) (中文(简体) ).

### 保存关于开发模式的文件

当你跑的时候 `pnpm dev`发生两件事:

-   建造的设定为 `watch` 模式。 每次您保存您的文件时, 都会重建工程 .
-   创建本地服务器 `http://localhost:3000` 它为您所有的项目文件服务。 您可以在您的 Webflow 工程中导入 :

```html
<script defer src="http://localhost:3000/{FILE_PATH}.js"></script>
```

-   Live Reloading是默认启用的,这意味着每次您保存文件的更改时,您正在工作的网站会自动重新加载. 你可以在其中禁用它 `/bin/build.js`。 。 。 .

### 构建多个文件

如果需要将多个文件构建到不同的输出中,可以通过更新构建设置来完成.

单位 `bin/build.js`,更新 `ENTRY_POINTS` 包含您想要构建的任何文件的阵列 :

```javascript
const entryPoints = [
  'src/home/index.ts',
  'src/contact/whatever.ts',
  'src/hooyah.ts',
  'src/home/other.ts',
];
```

这个会告诉 `esbuild` 来构建所有这些文件,并在 `dist` 用于制作和输入的文件夹 `http://localhost:3000` 促进发展.

### 设置路径别名

路径别名非常有助于避免诸如:

```typescript
import example from '../../../../utils/example';
```

相反,我们可以创建路径别名,将地图映射到特定的文件夹,所以代码变得更清洁,比如:

```typescript
import example from '$utils/example';
```

您可以使用 `paths` 设置在 `tsconfig.json`。本模板有一个预定义的路径作为示例:

```json
{
  "paths": {
    "$utils/*": ["src/utils/*"]
  }
}
```

为了避免任何出人意料 需要一些时间来熟悉 [配置图](https://npmcn.com/tsconfig.json) 启用了旗帜 .

## 测试

如前所述,这个图书馆 [剧作家](https://playwright.dev/) 作为自动测试工具列入.

所有试验都位于 `/tests` 文件夹。 此模板包含一个测试 spec 示例, 帮助您赶上 Playwright .

之后 [安装依赖关系](https://npmcn.com/package/%40finsweet/docs-theme/#readme-installing)你可以通过跑步来尝试 `pnpm test`。 。 。 . 确保用你自己的测试来代替它! 写适当的测试将有助于提高您的项目的长期可维持性和可扩展性.

默认情况下, Playwright 也会运行 `pnpm dev` 测试进行时的背景,所以 [您的文件已服务](https://npmcn.com/package/%40finsweet/docs-theme/#readme-serving-files-on-development-mode) 下级 `localhost:3000` 将一如既往地运行. 您可以在 `playwright.config.ts` 文档.

如果您的项目不需要任何测试, 您应该禁用测试中的工作 [CI 工作流程](https://npmcn.com/package/%40finsweet/docs-theme/#readme-continuous-integration) 通过评论出来在 `.github/workflows/ci.yml` 文档. 这将阻止测试运行 当你打开拉请求.

## 贡献指南

一般来说,你的开发工作流程应该是这样的:

1.  创建新分支, 用于开发新功能或错误修复 .
2.  一旦你完成了计划, [创建更改集](https://npmcn.com/package/%40finsweet/docs-theme/#readme-continuous-deployment) (或多)解释你在密码库所做的改变.
3.  打开拉请求并等待 [CI 工作流程](https://npmcn.com/package/%40finsweet/docs-theme/#readme-continuous-integration) 结束。 如果有什么失败,请在合并公关前尝试修复. 如果您不想等待 CI 工作流程运行在 GitHub 上以便知道是否有故障,那么在打开公关前在您的机器中运行它们总是会更快.
4.  合并拉动请求. 更改ets bot 将自动打开新的 PR 并更新到 `CHANGELOG.md`,你也应该合并这个。 如果你有的话 [自动 npm 部署](https://npmcn.com/package/%40finsweet/docs-theme/#readme-how-to-automatically-deploy-updates-to-npm) 启用后, 更改器也会在 npm 上发布此新版本 .

如果您在 npm 发布新版本之前需要研究多个特性, 创建一个 `development` 将所有公关合并到哪个分支 然后再将代码推向主机.

## 预定义脚本

本模板包含一组在 `package.json` 文件 :

-   `pnpm dev`: 构建并创建一个服务于所有文件的本地服务器( 请检查 [保存关于开发模式的文件](https://npmcn.com/package/%40finsweet/docs-theme/#readme-serving-files-on-development-mode) 以获得更多信息.
-   `pnpm build`: 构建到生产目录上 (`dist`) (中文(简体) ).
-   `pnpm lint`:用 ESLint 和 Prettier 扫描密码库,看看是否有出错.
-   `pnpm lint:fix`:在ESLint中解决所有可自动固定的问题.
-   `pnpm check`:检查代码库中TypeScript出错.
-   `pnpm format`: 使用 Pretier 格式化代码库中的所有文件。 你可能不需要这个脚本 如果你有自动 [保存时的格式](https://www.digitalocean.com/community/tutorials/code-formatting-with-prettier-in-visual-studio-code#automatically-format-on-save) 在编辑器中活动.
-   `pnpm test`: 将运行位于 `/tests` 文件夹.
-   `pnpm test:headed`: 将运行位于 `/tests` 在标题浏览器中可视化文件夹.
-   `pnpm release`: 此命令定义为 [更改](https://github.com/changesets/changesets)你不必和它互动.
-   `pnpm run update`:扫描工程的依赖性,并提供一个交互的UI来选择要更新的.

## 排雷中心/发改委

本模板包含一组具有适当的CI/CD工作流程的帮助.

### 持续整合

当您打开 Pull 请求时, 持续集成工作流程将运行到:

-   Lint 检查您的代码( R) 。 它使用 `pnpm lint` 财务报告和审定财务报表 `pnpm check` 在引擎盖下命令.
-   运行自动化测试。 它使用 `pnpm test` 在引擎盖下指挥.

如果其中任何一项工作失败, 您将在您的 Pull 请求中收到警告, 并尝试相应修改您的代码 .

**说明:** 如果你的项目没有包含任何定义的测试 `/tests` 文件夹中,您可以通过在 `.github/workflows/ci.yml` 文档。 这将大大地改善工作流程运行时间.

### 持续部署

[更改](https://github.com/changesets/changesets) 允许我们在将 Pull 请求合并到 `master` 树枝.

要生成新的更改日志, 运行 :

```bash
pnpm changeset
```

你会被催促 几个问题完成更改日志.

一旦拉动请求合并为 `master`,将自动打开一个新的 Pull 请求 `CHANGELOG.md` 文档. 你必须手动合并这个新的PR来完成工作流程.

如果一个 `NPM_TOKEN` secret 包含在寄存器的密件中, Deffersets 将自动将新软件包版本部署到 npm . 不断读取关于此事的更多信息.

#### 如何自动向 npm 部署更新

如前所述,如果一个 `NPM_TOKEN` 提供了秘密.

这个npm符号应该是:

-   来自Finsweetnpm组织,如果这个寄存器是用于内部/产品开发.
-   如果此寄存器是用于客户端开发,则来自客户端npm组织. 在这种情况下,你应该要求客户端 [创建 npm 账户](https://www.npmjs.com/signup) 并提供证明(或npm的标志)给你们.

输入 npm 账户后,就可以通过下列方式获得访问符 [本指南](https://docs.npmjs.com/creating-and-viewing-access-tokens)。 。 。 .

访问符必须放在 [存储器密钥](https://docs.github.com/en/codespaces/managing-codespaces-for-your-organization/managing-encrypted-secrets-for-your-repository-and-organization-for-codespaces#adding-secrets-for-a-repository) 名称 `NPM_TOKEN`。 。 。 .

## 常见问题

### @finsweet/docs-theme 是什么？

Finsweet 项目的官方docs启动模板\.

### 如何安装 @finsweet/docs-theme？

在项目目录运行 npm install @finsweet/docs-theme，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：vue（^3\.2\.47）、vitepress（^1\.0\.0-alpha\.49）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @finsweet/docs-theme 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/finsweet\_\_docs-theme 是否存在。

### @finsweet/docs-theme 支持 ESM 还是 CommonJS？

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

### @finsweet/docs-theme 可以商用吗？

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

### @finsweet/docs-theme 的下载量有多少？

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

### @finsweet/docs-theme 还在维护吗？

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