# aardio 工程文件（*.aproj）格式规范

> 发布日期：2026-10-20

## 1. 概述

aardio 工程文件的后缀名为 `.aproj`，采用 UTF-8 编码的 XML 格式存储工程配置、目录结构与发布参数。

- **默认文件名**：工程文件通常默认命名为 `default.aproj`。虽然一个工程目录下允许存放多个 `*.aproj` 文件，但实际开发中通常只使用一个 `default.aproj`。
- **工程根目录**：`*.aproj` 所在的目录即为工程根目录，同时也是开发运行时的[应用程序基准目录](../library-guide/builtin/io/path.html#app-path)（代码中以单个 `/` 或 `\` 开头的虚拟绝对路径即锚定于该目录）。
- **用户库目录（`/lib/`）**：`*.aproj` 文件中**不**记录 `/lib/` 用户库目录及其下的文件节点。用户库由 aardio 开发环境动态扫描与加载，在工程管理器的视图中会自动显示「用户库」目录；通过代码或外部工具增删用户库文件后，可调用 `ide.refreshUserLib()` 刷新用户库目录列表与智能提示数据。

## 2. 文件示例

### 2.1 标准桌面窗口工程示例

```xml
<?xml version="1.0" encoding="utf-8"?>
<project ver="10" name="Gif123" libEmbed="true" icon="\app.ico" ui="win" output="Gif123.exe" CompanyName="aardio" FileDescription="Gif123" LegalCopyright="Copyright (C) aardio.com 2022" ProductName="Gif123" InternalName="Gif123" FileVersion="3.4.0.0" ProductVersion="3.4.0.0" publishDir="/dist/" dstrip="true" local="false" ignored="false">
	<file name="main.aardio" path="main.aardio" comment="main.aardio"/>
	<folder name="资源文件" path="res" embed="true" local="false" ignored="false"/>
	<folder name="窗体文件" path="dlg" comment="目录" embed="true" local="false" ignored="false">
		<folder name="setting" path="dlg\setting" embed="true" comment="目录" local="false" ignored="false">
			<file name="setting.aardio" path="dlg\setting\setting.aardio" comment="dlg\setting\setting.aardio"/>
			<file name="recorder.aardio" path="dlg\setting\recorder.aardio" comment="dlg\setting\recorder.aardio"/>
			<file name="gif.aardio" path="dlg\setting\gif.aardio" comment="dlg\setting\gif.aardio"/>
		</folder>
	</folder>
</project>
```

### 2.2 含 Web 前端工程目录的示例

```xml
<?xml version="1.0" encoding="utf-8"?>
<project ver="37" name="WebViewApp" libEmbed="true" icon="..." ui="win" output="WebViewApp.exe" CompanyName="aardio" FileDescription="WebViewApp" LegalCopyright="Copyright (C) aardio 2026" ProductName="WebViewApp" InternalName="WebViewApp" FileVersion="1.0.0.0" ProductVersion="1.0.0.0" publishDir="/dist/" dstrip="false" local="false" ignored="false">
	<file name="main" path="main.aardio"/>
	<folder name="窗体" path="forms" comment="" embed="true" local="false" ignored="false"/>
	<folder name="网页" path="web" embed="true" comment="目录" local="true">
		<file name="index.html" path="web\index.html" comment="web\index.html"/>
		<file name="index.js" path="web\index.js" comment="web\index.js"/>
	</folder>
	<folder name="网页源码" path="web.src" embed="false" comment="目录" local="false" ignored="true"/>
</project>
```

## 3. 元素与属性规范

### 3.1 `<project>` 根元素

`<project>` 元素用于定义工程全局配置与编译发布信息，并作为工程根目录节点包含 `<folder>` 或 `<file>` 子元素。

| 属性名 | 类型 | 默认值/典型值 | 说明 |
| :--- | :--- | :--- | :--- |
| `ver` | 字符串 | `"10"` | 兼容的最小 aardio 主版本号，固定为 "10"。 |
| `name` | 字符串 | 工程名称 | 显示在工程管理器顶层节点的工程名称。 |
| `ui` | 字符串 | `"win"` | 界面与子系统类型，可选值：`win`、`console`、`website`。 |
| `output` | 字符串 | `"*.exe"` | 发布时生成的目标可执行文件名称（如 `"Gif123.exe"`）。 |
| `publishDir` | 字符串 | `"/dist/"` | 发布输出目录（相对于工程根目录的路径）。 |
| `icon` | 字符串 | `"\app.ico"` 或 `"..."` | EXE 图标文件路径（相对于工程根目录）；设为 `"..."` 或空串时使用默认图标。 |
| `libEmbed` | 布尔字符串 | `"true"` | 是否将引用的 aardio 库编译并内嵌到 EXE 资源中。 |
| `dstrip` | 布尔字符串 | `"false"` | 发布时是否移除调试符号信息。 |
| `CompanyName` | 字符串 | 公司/作者名 | EXE 版本信息资源：公司/单位名称。 |
| `FileDescription` | 字符串 | 工程描述 | EXE 版本信息资源：文件说明。 |
| `LegalCopyright` | 字符串 | 版权声明 | EXE 版本信息资源：版权信息。 |
| `ProductName` | 字符串 | 产品名称 | EXE 版本信息资源：产品名称。 |
| `InternalName` | 字符串 | 内部名称 | EXE 版本信息资源：内部名称。 |
| `FileVersion` | 字符串 | `"0.0.0.1"` | EXE 版本信息资源：文件版本号（`主版本.次版本.构建号.修订号`）。 |
| `ProductVersion` | 字符串 | `"0.0.0.1"` | EXE 版本信息资源：产品版本号（`主版本.次版本.构建号.修订号`）。 |
| `local` | 布尔字符串 | `"false"` | 在 `<project>` 根节点上固定为 `"false"`，不可更改。 |
| `ignored` | 布尔字符串 | `"false"` | 在 `<project>` 根节点上固定为 `"false"`，不可更改。 |

#### 关键属性详解

- **`ui`（用户界面与目标类型）**：
  - `"win"`：图形界面程序，发布后运行 EXE 时默认不显示控制台窗口。
  - `"console"`：控制台程序，发布后运行 EXE 时默认显示控制台窗口。
  - `"website"`：网站程序，发布时仅编译与部署网站文件到发布目录，**不会**生成 EXE 文件。
- **`libEmbed`（是否内嵌库）**：
  - `"true"`（默认）：编译工程引用的 aardio 库文件并嵌入到生成的 EXE 资源文件中，PE 资源类型名为 `"LIB"`，资源名称为转换为大写的库命名空间。
  - `"false"`：不将库嵌入 EXE，发布时仅将库文件复制到 `发布目录/lib/` 目录下。
- **`dstrip`（是否移除调试符号）**：
  - `"true"`：发布后移除调试符号信息，生成的文件体积更小，但运行时若抛出异常将缺少文件名、行号等调试信息。
  - `"false"`：保留调试符号信息。
- **EXE 版本资源字段**：
  `CompanyName`、`FileDescription`、`LegalCopyright`、`ProductName`、`InternalName`、`FileVersion`、`ProductVersion` 直接对应写入生成 EXE 资源文件的版本信息（VERSIONINFO）字段。
- **根节点固定属性**：
  对于 `<project>` 节点，`local="false" ignored="false"` 是固定不变的属性值。

---

### 3.2 `<folder>` 虚拟目录元素

`<folder>` 元素表示工程中的目录节点，可嵌套包含子级 `<folder>` 或 `<file>` 元素。

| 属性名 | 类型 | 默认值/典型值 | 说明 |
| :--- | :--- | :--- | :--- |
| `name` | 字符串 | 目录显示名 | 显示在工程视图中的友好名称（如 `"资源文件"`、`"窗体文件"`）。 |
| `path` | 字符串 | 相对路径 | 对应的实际文件夹路径（相对于工程根目录，如 `"res"`、`"dlg\setting"`）。 |
| `comment` | 字符串 | `"目录"` 或路径 | 节点备注信息（可选）。 |
| `embed` | 布尔字符串 | `"true"` / `"false"` | 是否将该目录作为内嵌资源编译进 EXE 文件。 |
| `local` | 布尔字符串 | `"false"` | 是否作为本地目录处理（发布时打包该物理目录下的全部文件）。 |
| `ignored` | 布尔字符串 | `"false"` | 发布工程生成 EXE 时是否忽略此目录。 |

#### 关键属性详解

- **`embed`（内嵌资源目录）**：
  - 当 `embed="true"` 时，该目录在发布后会嵌入到 EXE 资源文件中（PE 资源类型名为 `"RES"`，资源名称为转换为大写的相对路径，可使用标准库 [fsys.res](../library-reference/fsys/res.html) 读取）。
  - aardio 中绝大多数函数与标准库都原生支持透明读取这种内嵌资源，无需额外修改代码。例如调用 `string.load("/res/test.txt")` 时，无论目标文件是开发期硬盘上的普通文件还是发布后嵌入 EXE 的资源文件，函数返回值完全一致，这是 aardio 的核心特性之一。
- **`local`（本地目录）**：
  - 当 `local="true"` 时，表示这是一个本地目录（通常用于指向 Web 前端工程构建后的发布目录，如 `"web"`）。
  - 发布为 EXE 时会自动添加该目录下的所有文件。
  - 这种目录在 IDE 工程视图中不展开显示完整的子级文件或目录列表，右键菜单中的「同步本地目录」对该目录也是无效的。
- **`ignored`（忽略目录）**：
  - 当 `ignored="true"` 时，表示该目录在发布时被忽略。
  - 通常用于指向包含 Web 前端工程源码的目录（如 `"web.src"`）或仅在开发期使用的测试目录（如 `"test"`）。工程运行与打包本身不需要这些多余的源码或中间文件，生成 EXE 时会自动跳过此类目录。

---

### 3.3 `<file>` 文件元素

`<file>` 元素表示添加到工程中的具体文件节点。

| 属性名 | 类型 | 说明 |
| :--- | :--- | :--- |
| `name` | 字符串 | 显示在工程视图中的友好名称（如 `"main.aardio"` 或 `"main"`）。 |
| `path` | 字符串 | 实际文件的相对路径（相对于工程根目录，如 `"main.aardio"`、`"dlg\setting\setting.aardio"`）。 |
| `comment` | 字符串 | 文件备注说明（可选，通常为文件的相对路径或用途说明）。 |

#### 工程根目录文件约束

1. **唯一启动文件**：在工程根目录（即 `<project>` 元素的直接子节点）下，**只能有一个**应用程序启动文件，其文件路径必须是 `main.aardio` 或以 `.main.aardio` 结束。
2. **禁止散落根目录文件**：除了上述唯一启动文件外，工程根目录下只能包含 `<folder>` 元素；其他所有代码文件或资源文件都必须存放在各自的子目录（`<folder>`）或用户库目录（`/lib/`）中。

## 4. 编程读写与自动化规范

### 4.1 读写工具

- 可使用标准库 [string.xml](../library-reference/string/xml.html) 或 [web.msxml](../library-reference/web/msxml.html) 解析与编辑 `*.aproj` 文件。
- 新建标准工程建议优先调用扩展库 `ide.project`（如 `ide.project.createWinform()`、`ide.project.createConsole()` 等）。
- 对于当前已在 IDE 中打开的工程，可通过 `ide.getProjectProperty(name)` 与 `ide.setProjectProperty(name, value)` 读写 `<project>` 根节点的工程属性。

### 4.2 IDE 打开状态下的同步限制与最佳实践

1. **避免直接覆写已打开的 `.aproj` 文件**：
   已经在 aardio 工程管理器中打开的工程文件，目前**不支持**自动同步硬盘上的外部修改；并且 aardio 在关闭工程或保存所有文档时会自动将内存中的工程配置写回硬盘，这会覆盖外部直接对 `.aproj` 文件所做的修改。
2. **AI 与自动化工具生成流程**：
   如果是 AI 或自动化脚本生成、修改 `*.aproj` 文件，应当在**完成所有对 `.aproj` 文件的编辑并落盘保存之后**，再调用 `ide.openProject()` 打开该工程文件。
3. **向已打开工程添加代码文件**：
   对于已经在 IDE 中打开的工程，如需新增代码模块，建议优先将代码文件放到工程的 `/lib/` 用户库目录下（无需修改 `*.aproj` 工程文件），随后调用 `ide.refreshUserLib()` 即可刷新工程视图中的「用户库」目录与智能提示数据。

   外部自动化程序在其他工程目录下添加文件，用户可在工程视图内右键点击对应工程目录，在右键菜单中点击`同步本地目录...`菜单项。但是工程目录的 `local` 属性为 `true` 时则不需要同同步本地目（同步会报错）。