> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 如何创建你的 package.json 文件

> Node.js 中 package.json 文件的完整指南：了解如何创建、配置脚本、管理依赖，并为生产环境部署准备你的项目。

# 📋 Node.js 的 package.json 文件

`package.json` 文件是任何 Node.js 项目的核心。它充当一个清单，列出依赖、定义自动化脚本，并配置项目的行为。

本指南教你如何配置一个健壮的 `package.json`，确保你的项目可复现、有条理，并与 Square Cloud 环境兼容。

***

<Steps>
  <Step title="初始化项目">
    创建该文件最安全的方式是使用 NPM CLI。进入项目根目录并选择以下选项之一：

    **选项 A：交互式（推荐新手使用）**
    逐步回答问题以配置自定义元数据。

    ```bash theme={null}
    npm init
    ```

    **选项 B：自动（默认）**
    立即生成文件并接受所有默认设置。

    ```bash theme={null}
    npm init -y
    ```
  </Step>

  <Step title="配置必要的元数据">
    打开生成的 `package.json`。对于一个专业的项目，请确保正确填写以下字段：

    * `name`：唯一的项目标识符（使用 kebab-case，例如 `my-project-api`）。
    * `version`：遵循 SemVer 标准（例如 `1.0.0`）。
    * `main`：应用的入口点（通常为 `index.js` 或 `src/index.js`）。
    * `type`：如果使用 ES Modules（import/export）则设为 `"module"`，或移除以使用 CommonJS（require）。
  </Step>

  <Step title="配置执行脚本">
    `scripts` 部分对自动化至关重要。你在这里定义应用应如何启动、测试或构建。

    ```json theme={null}
    "scripts": {
      "start": "node index.js",
      "test": "echo \"Error: no test specified\" && exit 1"
    }
    ```

    **关于在 Square Cloud 上的初始化：**
    尽管该环境会查找常见的模式，Square Cloud 提供了完全的灵活性。你可以（并且应该）明确配置系统应执行哪个命令来启动你的应用。

    例如，你可以在 dashboard 或 Square 配置文件中配置 **Start Command** 来执行 `npm run start`，从而确保上面定义的脚本被遵循。
  </Step>

  <Step title="管理依赖">
    这里存放着让你的代码在生产环境中运行所必需的核心库。要安装并自动保存到该列表中：

    ```bash theme={null}
    npm install package-name
    ```

    **注意 `devDependencies` 与在 Square Cloud 上的构建：**
    仅在本地开发中使用的工具（如 `eslint` 或 `prettier`）应保留在 `devDependencies` 中。

    <Warning>
      **重要：** Square Cloud 默认以生产模式执行安装，这意味着列在 `devDependencies` 中的包**不会**被安装。

      如果你需要在云端运行\*\*构建（build）\*\*过程（例如编译 TypeScript 或运行安装后脚本），必须将这些工具移到 `dependencies` 中。否则，构建将因缺少包而失败。
    </Warning>
  </Step>

  <Step title="使用高级功能">
    对于更复杂的项目，`package.json` 提供了强大的控制功能：

    **1. Overrides（强制版本）：**
    当你使用的某个依赖安装了带有多个漏洞的子依赖时非常有用。你可以强制将其解析到一个安全版本：

    ```json theme={null}
    "overrides": {
      "vulnerable-package": "2.0.1"
    }
    ```

    **2. Imports（路径别名）：**
    避免像 `../../../utils` 这样的长相对路径。借助 `imports`，你可以创建原生的内部快捷方式（需要较新版本的 Node）：

    ```json theme={null}
    "imports": {
      "#utils/*": "./src/utils/*.js",
      "#database": "./src/core/database.js"
    }
    ```

    这样就可以在代码中使用 `import db from '#database'` 进行导入。
  </Step>
</Steps>

***

## 💡 提示与最佳实践

* **语义化版本控制**：优先通过移除 `^` 来固定关键版本（例如使用 `"14.14.1"` 而非 `"^14.14.1"`），以防止自动更新破坏你的生产代码。
* **安全性**：定期运行 `npm audit` 以识别依赖中的漏洞。上面介绍的 `overrides` 字段是修复这些问题的理想方案。
* **Package-lock.json**：切勿删除或在 `.gitignore` 中忽略此文件。它保证了 Square Cloud 将安装与在你机器上正常运行时完全一致的依赖树。
* **组织性**：保持文件整洁。如果 `scripts` 部分变得过于庞大，可考虑使用外部自动化工具或拆分到多个文件中。

***

## 📄 最终文件示例

以下是一个现代且经过优化的 `package.json` 示例：

```json package.json theme={null}
{
  "name": "square-cloud-project",
  "version": "1.0.0",
  "description": "Professional Node.js API",
  "main": "src/index.js",
  "type": "module",
  "scripts": {
    "start": "node src/index.js",
    "lint": "eslint ."
  },
  "imports": {
    "#services/*": "./src/services/*.js"
  },
  "dependencies": {
    "discord.js": "14.14.1",
    "dotenv": "16.3.1",
    "typescript": "5.3.3" 
  },
  "devDependencies": {
    "eslint": "8.56.0"
  }
}
```

***

## 🚀 后续步骤

配置好你的 `package.json` 文件后：

1. 提交到你的 Git 仓库。
2. 将你的项目托管到 **Square Cloud**。
3. 通过 GitHub 配置自动 deploy。
4. 欢迎来到专业的 Node.js 应用托管！

一个结构良好的 `package.json` 文件是任何成功的 Node.js 应用的基础，可确保你的应用在 Square Cloud 上完美运行。