从0到1开发水印组件npm包 -环境准备

小蜗牛de代码实验室
36 阅读5分钟

第02章：环境准备

工欲善其事，必先利其器。这一章我们来准备开发环境。

📋 本章目标

  • ✅ 安装必要的开发工具
  • ✅ 创建项目目录
  • ✅ 初始化项目配置
  • ✅ 验证环境配置

预计时间：15分钟

1. 检查Node.js

1.1 检查是否已安装

打开终端，执行：

node -v
npm -v

期望输出：

v18.17.0  （或更高版本，至少v16+）
9.6.7     （或更高版本，至少v8+）

1.2 如果未安装

方式1：官网下载（推荐）

访问：nodejs.org/

下载LTS版本（长期支持版）

方式2：使用nvm（高级）

# Mac/Linux
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18

# Windows
# 下载 nvm-windows: https://github.com/coreybutler/nvm-windows

2. 选择包管理器

2.1 三种选择

包管理器速度磁盘占用推荐度
npm中大⭐⭐⭐
yarn快中⭐⭐⭐⭐
pnpm最快最小⭐⭐⭐⭐⭐

2.2 安装pnpm（推荐）

npm install -g pnpm

验证：

pnpm -v
# 输出：8.9.0

如果不想安装pnpm，用npm也完全可以！ 本教程两者都支持。

3. 创建项目

3.1 创建目录

# 在你喜欢的位置创建项目
mkdir watermark-package
cd watermark-package

3.2 初始化package.json

# 方式1：交互式（会问你一些问题）
npm init

# 方式2：快速初始化（推荐）
npm init -y

生成的package.json：

{
  "name": "watermark-package",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

3.3 创建目录结构

# 创建src目录
mkdir src

# 创建examples目录
mkdir examples

# 创建.gitignore
touch .gitignore

项目结构：

watermark-package/
├── src/
├── examples/
├── .gitignore
└── package.json

3.4 配置.gitignore

创建 .gitignore 文件：

# 依赖
node_modules/

# 构建产物
dist/
*.tgz

# 日志
*.log
npm-debug.log*

# 编辑器
.vscode/
.idea/
*.swp
*.swo

# 系统文件
.DS_Store
Thumbs.db

# 临时文件
.cache/
temp/

4. 安装开发依赖

4.1 安装TypeScript

pnpm add -D typescript
# 或 npm install --save-dev typescript

4.2 安装打包工具

pnpm add -D tsup
# 或 npm install --save-dev tsup

4.3 验证安装

# 查看安装的包
pnpm list
# 或 npm list

应该看到：

watermark-package@1.0.0
├── tsup@8.0.0
└── typescript@5.3.0

5. 配置TypeScript

5.1 创建tsconfig.json

# 自动生成配置文件
npx tsc --init

5.2 修改配置

打开 tsconfig.json，修改为：

{
  "compilerOptions": {
    /* 语言和环境 */
    "target": "ESNext",                          // 编译目标
    "lib": ["DOM", "ESNext"],                    // 包含的库
    "jsx": "preserve",                           // JSX处理
    
    /* 模块 */
    "module": "ESNext",                          // 模块系统
    "moduleResolution": "node",                  // 模块解析策略
    "resolveJsonModule": true,                   // 支持导入JSON
    
    /* 输出 */
    "outDir": "./dist",                          // 输出目录
    "declaration": true,                         // 生成.d.ts
    "declarationMap": true,                      // 生成声明映射
    "sourceMap": true,                           // 生成source map
    
    /* 类型检查 */
    "strict": true,                              // 启用严格模式
    "strictNullChecks": true,                    // 严格空值检查
    "noUnusedLocals": true,                      // 检查未使用的变量
    "noUnusedParameters": true,                  // 检查未使用的参数
    "noImplicitReturns": true,                   // 检查函数返回值
    
    /* 其他 */
    "esModuleInterop": true,                     // ES模块互操作
    "skipLibCheck": true,                        // 跳过库检查
    "forceConsistentCasingInFileNames": true     // 强制文件名大小写一致
  },
  "include": ["src/**/*"],                       // 包含的文件
  "exclude": ["node_modules", "dist"]            // 排除的文件
}

配置说明：

配置项作用为什么需要
target: ESNext编译到最新JS现代浏览器都支持
lib: ["DOM"]包含DOM类型我们要操作DOM
declaration: true生成类型定义让用户有类型提示
strict: true严格模式发现潜在bug

6. 配置package.json

6.1 修改package.json

打开 package.json，修改为：

{
  "name": "@your-name/watermark",
  "version": "1.0.0",
  "description": "一个轻量级、高性能的水印组件",
  "keywords": ["watermark", "canvas", "typescript"],
  "author": "Your Name <your.email@example.com>",
  "license": "MIT",
  
  "main": "./dist/index.js",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  },
  
  "files": [
    "dist",
    "README.md"
  ],
  
  "scripts": {
    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
    "type-check": "tsc --noEmit"
  },
  
  "devDependencies": {
    "tsup": "^8.0.0",
    "typescript": "^5.0.0"
  }
}

重要字段说明：

{
  "name": "@your-name/watermark",  // ⚠️ 改成你的npm用户名
  
  // 入口文件 - 让工具知道从哪里导入
  "main": "./dist/index.js",       // CommonJS入口
  "module": "./dist/index.mjs",    // ES Module入口
  "types": "./dist/index.d.ts",    // TypeScript类型入口
  
  // 现代化导出配置
  "exports": {
    ".": {
      "import": "./dist/index.mjs",   // import语句用这个
      "require": "./dist/index.js",   // require语句用这个
      "types": "./dist/index.d.ts"    // TypeScript用这个
    }
  },
  
  // 发布到npm时包含的文件
  "files": ["dist", "README.md"],
  
  // 脚本命令
  "scripts": {
    "build": "构建命令",
    "dev": "开发模式（监听文件变化）",
    "type-check": "类型检查"
  }
}

7. 编辑器配置

7.1 安装VSCode（推荐）

如果还没有安装，访问：code.visualstudio.com/

7.2 推荐插件

打开VSCode，安装以下插件：

  1. TypeScript - 内置，无需安装
  2. ESLint - 代码检查
  3. Prettier - 代码格式化
  4. Path Intellisense - 路径提示

7.3 VSCode配置

创建 .vscode/settings.json：

{
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib"
}

8. 验证环境

8.1 创建测试文件

创建 src/index.ts：

export function hello(): string {
  return 'Hello, Watermark!';
}

8.2 运行构建

npm run build

应该看到：

CLI Building entry: src/index.ts
CLI Build success in 123ms

8.3 检查构建产物

ls dist/

应该看到：

index.d.ts    # TypeScript类型定义
index.js      # CommonJS格式
index.mjs     # ES Module格式

8.4 测试类型定义

创建 test.ts：

import { hello } from './dist/index';

const message = hello();
console.log(message);  // 应该有类型提示

9. Git配置（可选）

9.1 初始化Git

git init

9.2 首次提交

git add .
git commit -m "Initial commit"

9.3 关联远程仓库

# 在GitHub创建仓库后
git remote add origin https://github.com/你的用户名/watermark-package.git
git push -u origin main

10. 环境检查清单

10.1 必需项

  • Node.js已安装（v16+）
  • npm/pnpm已安装
  • 项目目录已创建
  • package.json已配置
  • tsconfig.json已配置
  • 开发依赖已安装
  • 构建命令能正常运行
  • dist目录有正确的文件

10.2 推荐项

  • VSCode已安装
  • 推荐插件已安装
  • Git已初始化
  • .gitignore已配置

11. 常见问题

Q1: npm install很慢怎么办？

解决方案：使用国内镜像

# 临时使用
npm install --registry=https://registry.npmmirror.com

# 永久配置
npm config set registry https://registry.npmmirror.com

Q2: pnpm安装失败？

解决方案：使用npm

# 所有命令中的pnpm替换为npm即可
npm install
npm run build

Q3: TypeScript编译错误？

解决方案：检查配置

# 检查TS版本
npx tsc --version

# 重新安装
rm -rf node_modules
npm install

Q4: 找不到dist目录？

解决方案：运行构建命令

npm run build

12. 本章总结

你完成了什么？

✅ 安装了Node.js和npm
✅ 创建了项目目录结构
✅ 配置了TypeScript
✅ 配置了打包工具
✅ 验证了环境配置
✅ 可以开始编码了！

下一步

环境准备好了，接下来我们要学习开发所需的基础知识。

📝 本章检查清单

  • Node.js版本 >= v16
  • package.json已正确配置
  • tsconfig.json已正确配置
  • 能成功运行 npm run build
  • dist目录有3个文件（.js .mjs .d.ts）
  • VSCode能正确识别TypeScript

全部完成？继续下一章 → 03-Canvas基础

💡 专业建议

  1. 保持依赖最新

    npm outdated  # 检查过时的包
npm update    # 更新包

  2. 使用版本管理

    git tag v1.0.0
git push --tags

  3. 定期备份

    • 推送到GitHub
    • 本地多个备份

准备好了吗？让我们开始学习Canvas！🎨

avatar
文章
阅读
粉丝