複製檔案外掛

外掛套件	@rushstack/heft (內建)
外掛名稱	copy-files-plugin 由 CopyFilesPlugin.ts 實作
外掛組態檔	(無)
heft.json 選項	copy-files-options.schema.json

此外掛會複製使用各種萬用字元指定的文件或資料夾。

何時使用

常見使用情境

• 將資產檔案（例如圖片或字型）複製到「dist」資料夾中
• 在編譯之前將 .d.ts 檔案複製到 temp/typings 資料夾中
• 複製 node_modules 相依項要重新封裝

一些注意事項

• 不建議使用 copy-files-plugin 將資產複製到 TypeScript 發射資料夾；改用 staticAssetsToCopy，因為它與 additionalModuleKindsToEmit 和觀察模式互動得更好。
• 避免使用此工作來讀取/寫入專案資料夾外的檔案。這樣做會違反 Rush 的 專案隔離原則。
• 如果可能，避免使用會遞迴搜尋目錄樹的低效率 glob 運算子（例如 **）。這些耗用磁碟密集的運作會減緩建置速度。
• 有些情況下，過於寬鬆的萬用字元可能包含 Git 中未追蹤的雜亂資料夾。

package.json 相依性

無 - 此功能內建於 @rushstack/heft。

組態

copy-files-plugin 是從 @rushstack/heft 直接載入的內建外掛程式。以下是載入此外掛程式的任務程式碼範例

<專案資料夾>/config/heft.json

{
  "$schema": "https://developer.microsoft.com/json-schemas/heft/v0/heft.schema.json",
  "extends": "@rushstack/heft-web-rig/profiles/library/config/heft.json",

  "phasesByName": {
    // ("build" is a user-defined name, not a schema field)
    "build": {
      "tasksByName": {
        // ("post-compile-copy" is a user-defined name, not a schema field)
        "post-compile-copy": {
          // The "post-compile-copy" task should not run until after "typescript" completes
          "taskDependencies": ["typescript"],

          "taskPlugin": {
            "pluginName": "copy-files-plugin",
            "pluginPackage": "@rushstack/heft",

            // --------------------------------------------------------------
            // EXAMPLE OPTIONS FOR copy-files-plugin
            "options": {
              "copyOperations": [
                {
                  "sourcePath": "assets/images",
                  "destinationFolders": ["dist"],
                  "fileExtensions": [ ".png", ".jpg" ]
                }
              ]
            }
            // --------------------------------------------------------------
          }
        }
      }
    }
  }
}

heft.json 外掛程式選項

此含註解範本記載可用的選項。在以上範例中，它會貼到 ------ 橫線之間。

// OPTIONS FOR copy-files-plugin
// JSON Schema: https://developer.microsoft.com/json-schemas/heft/v0/copy-files-options.schema.json
"options": {
  /**
   * An array of copy operations to be performed by this task.
   */
  "copyOperations": [
    /**
     * (REQUIRED) One or more folders that files and folders will be copied into,
     * relative to the project root.
     */
    "destinationFolders": [ "dist" ],

    /**
     * Absolute path to the source file or folder, relative to the project root.
     * If "fileExtensions", "excludeGlobs",  or "includeGlobs" are specified, then "sourcePath"
     * is assumed to be a folder; if it is not a folder, an error will be thrown.
     * Settings such as "includeGlobs" and "excludeGlobs" will be resolved relative to this path.
     * If no globs or file extensions are specified, the entire folder will be copied.
     * If this parameter is not provided, it defaults to the project root.
     */
    // "sourcePath": "assets/images",

    /**
     * If specified, this option recursively scans all folders under "sourcePath" and includes
     * any files that match the specified extensions.  If "fileExtensions" and "includeGlobs"
     * are both specified, their selections are added together.
     */
    // "fileExtensions": [ ".png" ],

    /**
     * A list of glob patterns that select files to be copied.  The paths are resolved relative
     * to "sourcePath", which must be a folder path.  If "fileExtensions" and "includeGlobs"
     * are both specified, their selections are added together.
     *
     * For glob syntax, refer to: https://www.npmjs.com/package/fast-glob
     */
    // "includeGlobs": [],

    /**
     * A list of glob patterns that exclude files or folders from being copied.  The paths are resolved
     * relative to "sourcePath", which must be a folder path.  These exclusions eliminate items that
     * were selected by the "includeGlobs" or "fileExtensions" setting.
     *
     * For glob syntax, refer to: https://www.npmjs.com/package/fast-glob
     */
    // "excludeGlobs": [ "**/temp" ],

    /**
     * Normally, copying will preserve the path relative to "sourcePath" under the destination folder.
     * (For example, if "sourcePath" is "src/test" and "destinationFolders" is ["out"], then
     * "src/test/a/b/c.txt" will be copied to "out/a/b/c.txt".)  Specify "flatten: true" to discard
     * path information and keep only the filename (for example, "out/c.txt").  If two files have
     * the same name, an error will be reported. The default value is false.
     */
    // "flatten": true,

    /**
     * If true, filesystem hard links will be created instead of copying the file.  Depending on the
     * operating system, this may be faster.  The default value is false.
     *
     * NOTE: This may cause unexpected behavior if a tool modifies the link. The contained directory
     * structure will be re-created and all files will be individually hardlinked.  This means that
     * folders will be new filesystem entities and will have separate folder metadata, while the
     * contained files will maintain normal hardlink behavior.  This is done since folders do not
     * have a cross-platform equivalent of a hardlink, and since file symlinks provide fundamentally
     * different functionality in comparison to hardlinks.
     */
    // "hardlink": true
  ]
}