Skip to main content
package.json 文件是任何 Node.js 项目的核心。它充当一个清单，列出依赖、定义自动化脚本，并配置项目的行为。 本指南教你如何配置一个健壮的 package.json，确保你的项目可复现、有条理，并与 Square Cloud 环境兼容。
1

初始化项目

创建该文件最安全的方式是使用 NPM CLI。进入项目根目录并选择以下选项之一：选项 A：交互式（推荐新手使用） 逐步回答问题以配置自定义元数据。
选项 B：自动（默认） 立即生成文件并接受所有默认设置。
2

配置必要的元数据

打开生成的 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）。
3

配置执行脚本

scripts 部分对自动化至关重要。你在这里定义应用应如何启动、测试或构建。
关于在 Square Cloud 上的初始化： 默认情况下，Square Cloud 会运行 node MAIN（即 MAIN 中设置的文件），但它提供了完全的灵活性。你可以（并且应该）明确配置系统应执行哪个命令来启动你的应用。例如，你可以在 dashboard 或 Square 配置文件中配置 Start Command 来执行 npm run start，从而确保上面定义的脚本被遵循。
4

管理依赖

这里存放着让你的代码在生产环境中运行所必需的核心库。要安装并自动保存到该列表中：
注意 devDependencies 与在 Square Cloud 上的构建： 仅在本地开发中使用的工具（如 eslint 或 prettier）应保留在 devDependencies 中。
重要： Square Cloud 默认以生产模式执行安装，这意味着列在 devDependencies 中的包不会被安装。如果你需要在云端运行 构建（build） 过程（例如编译 TypeScript 或运行安装后脚本），必须将这些工具移到 dependencies 中。否则，构建将因缺少包而失败。
5

使用高级功能

对于更复杂的项目，package.json 提供了强大的控制功能：1. Overrides（强制版本）： 当你使用的某个依赖安装了带有多个漏洞的子依赖时非常有用。你可以强制将其解析到一个安全版本：
2. Imports（路径别名）： 避免像 ../../../utils 这样的长相对路径。借助 imports，你可以创建原生的内部快捷方式（需要较新版本的 Node）：
这样就可以在代码中使用 import db from '#database' 进行导入。

​
提示与最佳实践

  • 语义化版本控制：优先通过移除 ^ 来固定关键版本（例如使用 "14.14.1" 而非 "^14.14.1"），以防止自动更新破坏你的生产代码。
  • 安全性：定期运行 npm audit 以识别依赖中的漏洞。上面介绍的 overrides 字段是修复这些问题的理想方案。
  • package-lock.json：请将它保留在 Git 中：它记录了在你电脑上正常运行的确切依赖树。Square Cloud CLI 和 VS Code 扩展默认不会在上传中包含锁文件，因此 Square Cloud 会安装 package.json 中版本范围允许的最新版本。如果你需要锁定的版本，请在你的 squarecloud.ignore 中用 !package-lock.json 重新包含它。
  • 组织性：保持文件整洁。如果 scripts 部分变得过于庞大，可考虑使用外部自动化工具或拆分到多个文件中。

​
最终文件示例

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

​
后续步骤

配置好你的 package.json 文件后：
  1. 将它提交到你的 Git 仓库。
  2. 通过 Node.js 运行时指南 托管你的项目，或参阅框架指南，例如 Express 或 Next.js。
  3. 每次推送时从 GitHub 自动部署。