# ini 中文文档

规范地址：https://npmcn.com/package/ini/

版本：7\.0\.0
npm 元数据更新时间：2026-09-09T20:10:54.191Z
中文译文更新时间：2026-11-04T19:17:13.140Z
软件包许可：ISC

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

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

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

- 包体积（解压后）：12.1 kB，4 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：^22\.22\.2 \|\| ^24\.15\.0 \|\| \>=26\.0\.0
- 运行依赖：0 个
- 首次发布：2011-08-07T07:05:10.072Z
- 最新版本发布：2026-05-08T18:36:26.841Z
- 近 30 天下载量：683568538（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：29（近 12 个月 1 个）

## 中文简介

用于node的ini编码器/解码器

## 安装

```sh
npm install ini
```

也可以使用：`pnpm add ini`、`yarn add ini`、`bun add ini`

## README

一个INI格式解析器和序列化器。

## 请注意

-   section被视为嵌套对象。
    
-   无节项被视为全局项。
    

## 用法

考虑如下的INI文件：

```ini
; This comment is being ignored
scope = global

[database]
user = dbuser
password = dbpassword
database = use_this_database

[paths.default]
datadir = /var/lib/data
array[] = first value
array[] = second value
array[] = third value
```

你可以 **读**， **修改** 和 **写** 它是这样的：

```js
import { writeFile , readFile } from 'node:fs/promises'
import { stringify , parse } from 'ini'

//  Read INI file as text

let text = await readFile(`./Original.ini`,{
    encoding : 'utf-8'
})

//  Parse text data to object

const config = parse(text)

//  Modify data object

config.scope = 'local'
config.database.database = 'use_another_database'
config.paths.default.tmpdir = '/tmp'
delete config.paths.default.datadir
config.paths.default.array.push('fourth value')

//  Stringify data object

text = stringify(config,{ 
    section : 'section' 
})

//  Write INI file as text

await writeFile(`./Modified.ini`,text)
```

书面文件将包括以下内容：

```ini
[section]
scope=local
[section.database]
user=dbuser
password=dbpassword
database=use_another_database
[section.paths.default]
tmpdir=/tmp
array[]=first value
array[]=second value
array[]=third value
array[]=fourth value
```

## API

### 解析

尝试将给定的INI字符串转换为嵌套的数据对象。

```js
// You can also use `decode`
const object = parse(`<INI Text>`) 
```

### Stringify

将给定的数据对象编码为INI格式的字符串。

```js
// You can also use `encode`
stringify(object,{

    /**
     *  Whether to insert spaces before & after `=`
     * 
     *  Disabled by default to have better 
     *  compatibility with old picky parsers.
     */

    whitespace : false ,

    /**
     *  Whether to align the `=` character for each section.
     *  -> Also enables the `whitespace` option
     */

    align : false ,

    /**
     *  Identifier to use for global items 
     *  and to prepend to all other sections.
     */

    section ,

    /**
     *  Whether to sort all sections & their keys alphabetically.
     */

    sort : false ,

    /**
     *  Whether to insert a newline after each section header.
     * 
     *  The TOSHIBA & FlashAir parser require this format. 
     */

    newline : false ,

    /**
     *  Which platforms line-endings should be used.
     * 
     *  win32 -> CR+LF
     *  other -> LF
     * 
     *  Default is the current platform
     */

    platform ,

    /**
     *  Whether to append `[]` to array keys.
     * 
     *  Some parsers treat duplicate names by themselves as arrays
     */

    bracketedArray : true

})
```

_为向后兼容，任何作为_  
_选项参数被视为 `section` 选择。_

```js
stringify(object,'section')
```

### Un / Escape

将给定的字符串转换为安全的  
在INI文件中使用key或value。

```js
safe(`"unsafe string"`) // -> \"unsafe string\"
```

或者用：

```js
unsafe(`\\"safe string\\"`) // -> "safe string"
```

## 常见问题

### ini 是什么？

用于node的ini编码器/解码器

### 如何安装 ini？

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

### ini 支持 TypeScript 吗？

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

### ini 支持 ESM 还是 CommonJS？

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

### ini 需要什么版本的 Node\.js？

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

### ini 可以商用吗？

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

### ini 的下载量有多少？

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

### ini 还在维护吗？

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